واجهة برمجة التطبيقات Google Play In-App Review API
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تتيح لك واجهة برمجة التطبيقات Google Play In-App Review API الطلب من المستخدمين إرسال تقييمات ومراجعات على "متجر Play" بدون الحاجة إلى مغادرة تطبيقك أو لعبتك.
بشكل عام، يمكن بدء مسار المراجعة داخل التطبيق (راجِع الشكل 1) في أي وقت خلال رحلة المستخدم داخل تطبيقك. وخلال هذا المسار، يمكن للمستخدم تقييم تطبيقك باستخدام نظام النجوم من 1 إلى 5 نجوم وإضافة تعليق اختياري. بعد إرسال المراجعة، يتم إرسالها إلى "متجر Play" وعرضها في النهاية.
الشكل 1. مسار المراجعة داخل التطبيق للمستخدم
متطلبات الأجهزة
لا تعمل المراجعات داخل التطبيق إلا على الأجهزة التالية:
أجهزة Android (الهواتف والأجهزة اللوحية وأجهزة التلفزيون التي تعمل بنظام التشغيل Google TV) التي تعمل بالإصدار 5.0 (المستوى 21 من واجهة برمجة التطبيقات) أو الإصدارات الأحدث والتي تم تثبيت "متجر Google Play" عليها
أجهزة ChromeOS التي تم تثبيت "متجر Google Play" عليها
متطلبات مكتبة Play Core
لدمج ميزة "المراجعات داخل التطبيق" في تطبيقك، يجب أن يستخدم تطبيقك الإصدار 1.8.0 أو إصدارًا أحدث من مكتبة Play Core.
متى يمكن طلب إجراء مراجعة داخل التطبيق؟
اتّبِع الإرشادات التالية لمساعدتك في تحديد الوقت المناسب لطلب مراجعات داخل التطبيق من المستخدمين:
يمكنك بدء تدفّق المراجعة داخل التطبيق بعد أن يجرّب المستخدم تطبيقك أو لعبتك بما يكفي لتقديم ملاحظات مفيدة.
لا تطلب من المستخدم بشكل مفرط كتابة مراجعة. تساعد هذه الطريقة في تقليل إحباط المستخدمين والحدّ من استخدام واجهة برمجة التطبيقات (راجِع القسم الخاص بالحِصص).
يجب ألا يطرح تطبيقك أي أسئلة على المستخدم قبل عرض زر التقييم أو البطاقة أو أثناء عرضهما، بما في ذلك أسئلة حول رأيه (مثل "هل أعجبك التطبيق؟") أو أسئلة تنبؤية (مثل "هل ستمنح هذا التطبيق 5 نجوم؟").
إرشادات التصميم
اتّبِع الإرشادات التالية عند تحديد كيفية دمج المراجعات داخل التطبيق في تطبيقك:
اعرض البطاقة كما هي، بدون التلاعب بالتصميم الحالي أو تعديله بأي شكل من الأشكال، بما في ذلك الحجم أو الشفافية أو الشكل أو الخصائص الأخرى.
لا تضِف أي تراكب فوق البطاقة أو حولها.
يجب أن تكون البطاقة وخلفيتها في الطبقة الأعلى. بعد ظهور البطاقة، لا تزِلها آليًا. تتم إزالة البطاقة تلقائيًا استنادًا إلى إجراء صريح من المستخدم أو آلية داخلية في "متجر Play".
الحصص
لتقديم تجربة رائعة للمستخدمين، يفرض Google Play حصة زمنية على عدد المرات التي يمكن فيها عرض مربّع حوار المراجعة للمستخدم. وبسبب هذا الحصص، قد لا يؤدي استدعاء الطريقة launchReviewFlow أكثر من مرة خلال فترة زمنية قصيرة (على سبيل المثال، أقل من شهر) إلى عرض مربّع حوار في بعض الأحيان.
بما أنّ الحصة قابلة للتغيير، من المهم تطبيق منطقك الخاص
واستهداف أفضل وقت ممكن لطلب إجراء مراجعة. على سبيل المثال، يجب ألا يتضمّن التطبيق خيارًا يحث المستخدم على اتّخاذ إجراء (مثل زر) لتفعيل واجهة برمجة التطبيقات،
لأنّه قد يكون المستخدم قد تجاوز الحصة المخصّصة له ولن يتم عرض المسار،
ما يؤدي إلى تقديم تجربة غير مكتملة للمستخدم. في حالة الاستخدام هذه، أعِد توجيه المستخدم إلى "متجر Play" بدلاً من ذلك.
دمج المراجعات داخل التطبيق في تطبيقك
تعرَّف على كيفية دمج ميزة "المراجعات داخل التطبيق" في تطبيقك، وذلك حسب بيئة التطوير التي تستخدمها:
مكتبات Play Core هي واجهة وقت التشغيل لتطبيقك مع "متجر Google Play". وبالتالي، عند استخدام Play Core في تطبيقك، ينفّذ "متجر Play" عملياته الخاصة، والتي تشمل معالجة البيانات وفقًا لبنود خدمة Google Play. توضّح المعلومات التالية كيفية معالجة مكتبات Play Core للبيانات من أجل تنفيذ طلبات محدّدة من تطبيقك.
المراجعات داخل التطبيق
البيانات التي يتم جمعها عن الاستخدام
البيانات التي يدخلها المستخدم (التقييم والمراجعة بنص حر)
الغرض من جمع البيانات
يتم استخدام البيانات التي يتم جمعها لإضافة مراجعة على "متجر Play".
تشفير البيانات
البيانات مشفّرة.
مشاركة البيانات
تُستخدم البيانات التي يتم جمعها في مراجعة علنية على "متجر Play"، أو إذا كان التطبيق في مسار اختبار مغلق، تتم مشاركة البيانات التي يتم جمعها بشكل خاص مع مطوّر التطبيق.
حذف البيانات
يمكن للمستخدمين حذف مراجعاتهم في حساباتهم على "متجر Google Play" أو حساباتهم على Google.
مع أنّنا نهدف إلى الالتزام بالشفافية قدر الإمكان، إلا أنّك وحدك المسؤول عن تحديد كيفية ملء نموذج قسم "أمان البيانات" في Google Play بشأن ممارسات جمع بيانات المستخدمين ومشاركتها وأمانها في تطبيقك.
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-08-08 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-08-08 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Google Play In-App Reviews API\n\nThe Google Play In-App Review API lets you prompt users to submit Play Store\nratings and reviews without the inconvenience of leaving your app or game.\n\nGenerally, the in-app review flow (see figure 1) can be triggered at any time\nthroughout the user journey of your app. During the flow, the user has the\nability to rate your app using the 1 to 5 star system and to add an optional\ncomment. Once submitted, the review is sent to the Play Store and eventually\ndisplayed.\n| **Note:** To protect user privacy and avoid API misuse, there are strict guidelines that your app should follow about [when to request in-app reviews](#when-to-request) and the [design of the review prompt](#design-guidelines).\n\n\n**Figure 1.** In-app review flow for a user\n\n\u003cbr /\u003e\n\nDevice requirements\n-------------------\n\nIn-app reviews only work on the following devices:\n\n- Android devices (phones, tablets, and TVs with Google TV) running Android 5.0 (API level 21) or higher that have the Google Play Store installed.\n- ChromeOS devices that have the Google Play Store installed.\n\nPlay Core library requirements\n------------------------------\n\nTo integrate in-app reviews in your app, your app must use version 1.8.0 or\nhigher of the [Play Core library](/guide/playcore).\n\nWhen to request an in-app review\n--------------------------------\n\nFollow these guidelines to help you decide when to request in-app reviews from\nusers:\n\n- Trigger the in-app review flow after a user has experienced enough of your app or game to provide useful feedback.\n- Don't prompt the user excessively for a review. This approach helps minimize user frustration and limit API usage (see the [section on quotas](#quotas)).\n- Your app shouldn't ask the user any questions before or while presenting the rating button or card, including questions about their opinion (such as \"Do you like the app?\") or predictive questions (such as \"Would you rate this app 5 stars\").\n\nDesign guidelines\n-----------------\n\nFollow these guidelines as you determine how to integrate in-app reviews in your\napp:\n\n- Surface the card as-is, without tampering or modifying the existing design in any way, including size, opacity, shape, or other properties.\n- Don't add any overlay on top of the card or around the card.\n- The card and the card's background should be on the topmost layer. Once the card has surfaced, don't programmatically remove the card. The card is removed automatically based on either the user's explicit action, or an internal Play Store mechanism.\n\nQuotas\n------\n\nTo provide a great user experience, Google Play enforces a time-bound quota on\nhow often a user can be shown the review dialog. Because of this quota, calling\nthe `launchReviewFlow` method more than once during a short period of time (for\nexample, less than a month) might not always display a dialog.\n| **Note:** The specific value of the quota is an implementation detail, and it can be changed by Google Play without any notice.\n\nBecause the quota is subject to change, it's important to apply your own logic\nand target the best possible moment to request a review. For example, **you\nshould not have a call-to-action option (such as a button) to trigger the API**,\nas a user might have already hit their quota and the flow won't be shown,\npresenting a broken experience to the user. For this use case, redirect the user\nto the Play Store instead.\n\nIntegrate in-app reviews in your app\n------------------------------------\n\nLearn how to integrate in-app reviews in your app, depending on your development\nenvironment:\n\n- [Kotlin or Java](/guide/playcore/in-app-review/kotlin-java)\n- [Native (C++)](/guide/playcore/in-app-review/native)\n- [Unity](/guide/playcore/in-app-review/unity)\n- [Unreal Engine](/guide/playcore/in-app-review/unreal-engine)\n\nTerms of service and data safety\n--------------------------------\n\nBy accessing or using the Play In-App Reviews Library, you agree to the [Play\nCore Software Development Kit Terms of Service](/guide/playcore#license). Read and understand all\napplicable terms and policies before accessing the library.\n\nData Safety\n-----------\n\nThe Play Core libraries are your app's runtime interface with the Google Play\nStore. As such, when you use Play Core in your app, the Play Store runs its own\nprocesses, which include handling data as governed by the [Google Play Terms of\nService](https://play.google.com/about/play-terms/index.html). The following information describes how the Play Core\nlibraries handle data to process specific requests from your app.\n\n### In-app Reviews\n\n|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Data collected on usage | User-entered data (rating and free-text review) |\n| Purpose of data collection | The data collected is used to leave a review on the Play Store. |\n| Data encryption | Data is encrypted. |\n| Data sharing | The data collected is used in a public review on the Play Store or, if the app is in a closed test track, the data collected is shared privately with the app developer. |\n| Data deletion | Users can delete their reviews in their Google Play Store account or Google Account. |\n\nWhile we aim to be as transparent as possible, you are solely responsible for\ndeciding how to respond to Google Play's data safety section form regarding your\napp's user data collection, sharing, and security practices."]]
