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

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

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

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

للعمل مع واجهة برمجة التطبيقات Reply to Reviews API، يجب منح التفويض باستخدام عميل 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، ويفصل حرف Tab العنوان عن النص الأساسي. يشير العنصر 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 مثل عنوان 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 طلب (للردّ على المراجعات) – 2000 طلب في اليوم

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