כתיבת תשובה לביקורות

ממשק ה-API של Google Play למפתחים מאפשר לכם להציג משוב משתמשים על האפליקציה שלכם ולהשיב למשוב הזה. אתם יכולים להשתמש ב-API הזה כדי ליצור אינטראקציה עם משתמשים ישירות בערכת הכלים הקיימת שלכם לתמיכת לקוחות, כמו מערכת CRM.

ממשק ה-API להשבת ביקורות מאפשר לכם לגשת למשוב רק על גרסאות ייצור של האפליקציה. אם אתם רוצים לראות משוב על גרסאות אלפא או בטא של האפליקציה, אתם צריכים להשתמש ב-Google Play Console. בנוסף, חשוב לזכור שה-API מציג רק את הביקורות שכוללות תגובות. אם משתמש מדרג את האפליקציה אבל לא מוסיף תגובה, המשוב שלו לא נגיש דרך ה-API.

קבלת גישה

כדי לעבוד עם Reply to Reviews API, צריך לספק הרשאה באמצעות לקוח OAuth או חשבון שירות. אם אתם משתמשים בחשבון שירות, אתם צריכים להפעיל את ההרשאה 'תגובה לביקורות' בחשבון הזה. מידע נוסף על הקמת גישה מורשית ל-API הזה זמין במאמר הגדרת לקוחות לגישה ל-API.

אחזור ביקורות

כשמשתמשים ב-Reply to Reviews API, אפשר לאחזר רשימה של כל הביקורות האחרונות על האפליקציה, או לראות ביקורת ספציפית.

אחזור של קבוצת ביקורות

משתמשים בשיטה GET כדי לבקש רשימה של ביקורות על האפליקציה. בבקשה צריך לכלול את שם החבילה המלא של האפליקציה – לדוגמה, com.google.android.apps.maps – ואת אסימון ההרשאה שקיבלתם כשקיבלתם גישה ל-API.

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 לא יופיע בתוצאה מסוימת.

תגובות

רשימה שכוללת את המשוב של המשתמש על האפליקציה. אם הביקורת כוללת כותרת, הכותרת וגוף הביקורת מופיעים שניהם ברכיב text, והכותרת מופרדת מגוף הביקורת באמצעות תו של טאב. רכיב lastModified מציין את השעה שבה המשתמש שלח את הביקורת שלו לאחרונה.

אם כבר הגבתם לביקורת הזו, המשוב שלכם יופיע כרכיב השני ברשימת התגובות.

starRating

הערכת המשתמש את האפליקציה בסולם של 1 עד 5. ציון של 5 מצביע על כך שהמשתמש מרוצה מאוד מהאפליקציה.

כברירת מחדל, בכל דף מופיעות 10 ביקורות. אפשר להציג עד 100 ביקורות בכל דף על ידי הגדרת הפרמטר maxResults בבקשה.

אם רשימת הביקורות ממשיכה לדף אחר, ה-API כולל רכיב 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

אחזור של ביקורת ספציפית

אפשר גם להשתמש ב-method 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
      }
    }
  ]
}

תרגום טקסט הביקורת

אפשר לתרגם אוטומטית את הטקסט של הביקורות לפני שהן מוחזרות מ-Reviews API. כשמאחזרים רשימה של ביקורות או ביקורת אחת, מוסיפים פרמטר 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 מציין את השעה שבה ה-API מתעד את התגובה שלכם לביקורת של המשתמש.

{
  "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 ביום

אם האפליקציה שלכם צריכה לאחזר או להשיב למספר גדול יותר של ביקורות מהמכסות האלה, אפשר לשלוח בקשה להגדלת המכסה של האפליקציה.