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

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

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

الحصول على إمكانية الوصول

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

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

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

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

استخدِم طريقة 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 المحددة غير موجودة.

الحصص

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

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

• POST طلب (للرد على المراجعات) – 2000 في اليوم

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