الردّ على المراجعات

تتيح لك واجهة برمجة التطبيقات "الردّ على المراجعات" من Google Play Developer API الاطّلاع على ملاحظات المستخدمين بشأن تطبيقك والردّ عليها. يمكنك استخدام واجهة برمجة التطبيقات هذه للتفاعل مع المستخدمين مباشرةً ضمن مجموعة أدوات دعم العملاء الحالية، مثل نظام إدارة علاقات العملاء (CRM).

تتيح لك واجهة برمجة التطبيقات Reply to Reviews API الوصول إلى الملاحظات الخاصة بإصدارات الإنتاج فقط من تطبيقك. إذا أردت الاطّلاع على الملاحظات الخاصة بإصدارات ألفا أو بيتا من تطبيقك، استخدِم Google Play Console بدلاً من ذلك. يُرجى العِلم أيضًا أنّ واجهة برمجة التطبيقات تعرض المراجعات التي تتضمّن تعليقات فقط. إذا قيّم المستخدم تطبيقك بدون تقديم تعليق، لن تتمكّن من الوصول إلى ملاحظاته من خلال واجهة برمجة التطبيقات.

الحصول على إذن الوصول

للعمل باستخدام واجهة برمجة التطبيقات "الردّ على المراجعات"، عليك تقديم إذن باستخدام عميل OAuth أو حساب خدمة. إذا كنت تستخدم حساب خدمة، فعِّل إذن "الردّ على المراجعات" في هذا الحساب. لمزيد من المعلومات حول إعداد وصول معتمد إلى واجهة برمجة التطبيقات هذه، يُرجى الاطّلاع على إعداد عملاء الوصول إلى واجهة برمجة التطبيقات.

استرداد المراجعات

عند استخدام Reply to Reviews API، يمكنك استرداد قائمة بجميع المراجعات الحديثة لتطبيقك، أو يمكنك الاطّلاع على مراجعة فردية.

استرداد مجموعة من المراجعات

استخدِم طريقة GET لطلب قائمة بمراجعات تطبيقك. في طلبك، أدرِج اسم الحزمة المؤهَّل بالكامل لتطبيقك، مثل com.google.android.apps.maps، ورمز التفويض الذي تلقّيته عند الحصول على إذن الوصول إلى واجهة برمجة التطبيقات.

GET https://www.googleapis.com/androidpublisher/v3/applications/your_package_name/reviews?
access_token=your_auth_token

الردّ عبارة عن سلسلة JSON تحتوي على قائمة بمراجعات تطبيقك. تعرض النتيجة الأولى في القائمة تعليق المستخدم الذي تم إنشاؤه أو تعديله مؤخرًا.

في المثال التالي، تعرض المراجعة الأولى بيانات وصفية تظهر في جميع النتائج، بينما تعرض المراجعة الثانية بيانات وصفية تظهر في بعض النتائج فقط:

{
  "reviews": [
    {
      "reviewId": "12345678",
      "authorName": "Jane Bloggs",
      "comments": [
        {
          "userComment": {
            "text": "This is the best app ever!",
            "lastModified": {
              "seconds": "1443676826",
              "nanos": 713000000
            },
            "starRating": 5
          }
        }
      ]
    },
    {
      "reviewId": "11223344",
      "authorName": "John Doe",
      "comments": [
        {
          "userComment": {
            "text": "I love using this app!",
            "lastModified": {
              "seconds": "141582134",
              "nanos": 213000000
            },
            "starRating": 5,
            "reviewerLanguage": "en",
            "device": "trltecan",
            "androidOsVersion": 21,
            "appVersionCode": 12345,
            "appVersionName": "1.2.3",
            "thumbsUpCount": 10,
            "thumbsDownCount": 3,
            "deviceMetadata": {
              "productName": "E5333 (Xperia™ C4 Dual)",
              "manufacturer": "Sony",
              "deviceClass": "phone",
              "screenWidthPx": 1080,
              "screenHeightPx": 1920,
              "nativePlatform": "armeabi-v7a,armeabi,arm64-v8a",
              "screenDensityDpi": 480,
              "glEsVersion": 196608,
              "cpuModel": "MT6752",
              "cpuMake": "Mediatek",
              "ramMb": 2048
            }
          }
        },
        {
          "developerComment": {
            "text": "That's great to hear!",
            "lastModified": {
              "seconds": "1423101467",
              "nanos": 813000000
            }
          }
        }
      ]
    }
  ],
  "tokenPagination": {
    "nextPageToken": "12334566"
  }
}

تتضمّن كل نتيجة البيانات الوصفية التالية:

reviewId

يحدّد هذه المراجعة بشكلٍ فريد. ويشير أيضًا إلى مراجعة مستخدم معيّن، لأنّه يمكن للمستخدمين كتابة مراجعة واحدة فقط لتطبيق معيّن.

authorName

تمثّل هذه السمة اسم المستخدم الذي يكتب المراجعة.

ملاحظة: في حالات نادرة، قد لا يظهر الرمز authorName في نتيجة معيّنة.

comments

قائمة تتضمّن ملاحظات المستخدم حول التطبيق. إذا كانت هذه المراجعة تتضمّن عنوانًا، سيظهر هذا العنوان ونص المراجعة الأساسي في العنصر text، ويفصل بين العنوان والنص الأساسي حرف علامة تبويب. يشير العنصر lastModified إلى الوقت الذي أرسل فيه المستخدم مراجعته آخر مرة.

إذا سبق لك الردّ على هذه المراجعة، ستظهر ملاحظاتك كالعنصر الثاني في قائمة التعليقات.

starRating

يشير إلى تقييم المستخدم لتطبيقك على مقياس من 1 إلى 5. تشير النتيجة 5 إلى أنّ المستخدم راضٍ جدًا عن تطبيقك.

يظهر تلقائيًا 10 مراجعات على كل صفحة. يمكنك عرض ما يصل إلى 100 مراجعة في الصفحة الواحدة من خلال ضبط المَعلمة maxResults في طلبك.

إذا استمرت قائمة المراجعات في صفحة أخرى، ستتضمّن واجهة برمجة التطبيقات العنصر tokenPagination في الردّ. عند طلب الصفحة التالية من المراجعات، يجب تضمين العنصر token. اضبط قيمة هذا العنصر على القيمة nextPageToken التي تظهر في الرد الأصلي.

ملاحظة: يمكنك استرداد المراجعات التي أنشأها المستخدمون أو عدّلوها خلال الأسبوع الماضي فقط. إذا أردت استرداد جميع المراجعات الخاصة بتطبيقك منذ البداية، يمكنك تنزيل مراجعاتك كملف CSV باستخدام Google Play Console.

يعرض المثال التالي لطلب GET الصفحة التالية من المراجعات. يفترض هذا الطلب أنّ الصفحة الحالية للمراجعات (كما هو موضّح في استجابة الطلب السابق) تتضمّن القيمة nextPageToken التي تساوي "12334566". يشير الطلب أيضًا إلى أنّ الصفحة التالية يجب أن تعرض ما يصل إلى 50 مراجعة.

GET https://www.googleapis.com/androidpublisher/v3/applications/your_package_name/reviews?
access_token=your_auth_token&token=12334566&maxResults=50

استرداد مراجعة فردية

يمكنك أيضًا استخدام طريقة GET لاسترداد مراجعة فردية. يجب تقديم عنوان URL نفسه المستخدَم في استرداد مجموعة من المراجعات، مع تضمين review_id المقابل للمراجعة التي تريد الاطّلاع عليها:

GET https://www.googleapis.com/androidpublisher/v3/applications/your_package_name/reviews/
review_id?access_token=your_auth_token

الردّ المناسب هو سلسلة JSON تتضمّن المحتوى والبيانات الوصفية لمراجعة واحدة:

{
  "reviewId": "87654321",
  "authorName": "Joan Smith",
  "comments": [
    {
      "userComment": {
        "text": "This app is awesome!",
        "lastModified": {
          "seconds": "1452114723",
          "nanos": 913000000
        },
        "starRating": 5
      }
    }
  ]
}

ترجمة نص المراجعة

يمكن ترجمة نص المراجعة تلقائيًا قبل إرجاعه من واجهة برمجة التطبيقات الخاصة بالمراجعات. عند استرداد قائمة مراجعات أو مراجعة واحدة، أضِف المَعلمة translationLanguage إلى طلب البحث. على سبيل المثال:

GET https://www.googleapis.com/androidpublisher/v3/applications/your_package_name/reviews?
access_token=your_auth_token&translationLanguage=en

يمكن أن تحدّد المَعلمة translationLanguage لغة مع بلد أو بدونه. على سبيل المثال، كلّ من "en" و "en_GB" صالحتان.

إذا حدّدت لغة ترجمة مختلفة عن النص الأصلي، سيعرض النظام النص المترجَم في السمة text والنص الأصلي في السمة originalText. وفي ما يلي مثال لذلك:

    {
      "reviewId": "12345678",
      "authorName": "Jane Bloggs",
      "comments": [
        {
          "userComment": {
            "text": "This is the best app ever!",
            "lastModified": {
              "seconds": "1443676826",
              "nanos": 713000000
            },
            "starRating": 5,
            "originalText": "Dies ist die beste App überhaupt!"
          }
        }
      ]
    }

الردّ على المراجعات

يمكنك أيضًا التفاعل مع مستخدمي تطبيقك من خلال الردّ على مراجعاتهم. بعد إرسال ردّك، يتلقّى المستخدم إشعارًا يشير إلى أنّك ردّيت على ملاحظاته.

ننصح بعدم استخدام الردود المبرمَجة على المراجعات، مع التخطيط لتعديل هذه الردود يدويًا في وقت لاحق. بالإضافة إلى ذلك، على الرغم من أنّه يمكنك الردّ على مراجعة عدة مرات، لن يتلقّى المستخدم إشعارًا إلا بعد أول ردّ على مراجعة تم إنشاؤها أو تعديلها. يوضّح الجدول التالي كيفية إرسال الإشعارات إلى المستخدم أثناء تفاعلك معه:

تفاعل المستخدم مع المطوّر	هل تم إرسال إشعار إلى المستخدم؟
يكتب المستخدم مراجعة ويرسل المطوّر ردًا عليها	نعم
ردود المطوّرين على المراجعة الأصلية	لا
يعدّل المستخدم المراجعة، ويعدّل المطوّر الردّ	نعم

ملاحظة: بما أنّ ردودك على المراجعات تظهر بشكل علني على صفحة متجر التطبيقات، من المهم عدم تضمين معلومات حساسة عن المستخدمين عند كتابة هذه الردود.

لإرسال ردّ على مراجعة أحد المستخدمين، استخدِم طريقة POST. في طلبك، حدِّد أنّ Content-Type هو application/json، وأدرِج مستند JSON يحتوي على ردّك:

POST https://www.googleapis.com/androidpublisher/v3/applications/your_package_name/reviews/
review_id:reply?access_token=your_access_token
Content-Type: application/json

{
  "replyText": "Thanks for your feedback!"
}

ملاحظة: يمكن أن يتضمّن replyText الذي تدرجه مع طلبك POST 350 حرفًا كحدّ أقصى. يجب استخدام نص عادي في ردّك، لأنّه تتم إزالة علامات HTML ذات التنسيق السليم ولا يتم تضمينها في عدد الأحرف المسموح به في ردّك. ومع ذلك، يتم الاحتفاظ بالمحتوى الذي تضعه داخل علامات HTML بتنسيق سليم.

إذا نجح طلبك، ستتلقّى سلسلة JSON التالية كاستجابة. يشير العنصر lastEdited إلى الوقت الذي يسجّل فيه واجهة برمجة التطبيقات ردّك على مراجعة المستخدم.

{
  "result": {
    "replyText": "Thanks for your feedback!",
    "lastEdited": {
      "seconds": "1453978803",
      "nanos": 796000000
    }
  }
}

في المقابل، إذا كان طلب POST غير صالح، ستعرض الاستجابة أحد رموز الخطأ التالية بدلاً من ذلك:

400 Bad Reply Request

replyText طويل جدًا أو مفقود.

404 Not Found

لا تتوفّر المراجعة التي تحمل review_id المحدّد.

الحصص

تقديرًا منا للمطوّرين الآخرين، تفرض Reply to Reviews API عدة حصص. يتم فرض هذه الحصص بشكل منفصل على أساس كل تطبيق على حدة:

• طلبات GET (لاسترداد قوائم المراجعات والمراجعات الفردية): 200 طلب في الساعة

• طلبات POST (للردّ على المراجعات): 2,000 طلب في اليوم

إذا كان تطبيقك يحتاج إلى استرداد عدد أكبر من المراجعات أو الردّ على عدد أكبر من المراجعات مما تسمح به هذه الحصص، يُرجى إرسال طلب لزيادة حصة تطبيقك.