回覆評論

Google Play Developer Reply to Review API 可讓您查看及回覆應用程式的使用者意見回饋。您可以使用這個 API,直接在客戶關係管理系統等現有客戶服務工具包中與使用者互動。

Reply to Review API 只能讓您存取應用程式正式版的意見回饋。如果您想查看 Alpha 版或 Beta 版應用程式的意見回饋,請改用 Google Play 管理中心。另請注意,這個 API 只會顯示包含留言的評論。如果使用者已對應用程式評分,但並未留言,您就無法透過這個 API 存取他們的意見回饋。

取得存取權

如要使用 Reply to Review 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 可能不會在特定結果中顯示。

comments

這份清單中包含使用者對應用程式的意見回饋。如果評論含有標題,則這個標題和評論的內文會同時顯示在 text 元素中,定位字元則會分隔標題和內文。lastModified 元素表示使用者最近提交評論的時間。

如果您已回覆這則評論,意見回饋會顯示在註解清單中的第二個元素。

starRating

使用者對應用程式的評分,以 1 至 5 分表示。5 分代表使用者非常滿意您的應用程式。

根據預設,每個頁面會顯示 10 則評論。在要求中設定 maxResults 參數,每個頁面最多可顯示 100 則評論。

如果評論清單繼續出現在其他頁面,API 會在回應中加入 tokenPagination 元素。要求下一頁審查時,請加入 token 元素。將這個元素的值設為原始回應中顯示的 nextPageToken 值。

注意:您只能擷取使用者在過去一週內建立或修改的評論。如果您想擷取一開始就擷取應用程式的所有評論,您可以使用 Google Play 管理中心,將評論下載為 CSV 檔案

以下 GET 要求範例會顯示下一頁的評論。這項要求假設目前的評論頁面 (如上一個要求的回應所示) 包含 "12334566"nextPageToken 值。要求也指出下一頁應顯示最多 50 則評論。

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

擷取個別評論

您也可以使用 GET 方法擷取個別評論。您提供的網址必須與擷取一組評論的網址相同,只須附上與想查看的評論對應的 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
      }
    }
  ]
}

翻譯評論文字

從評論 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-Typeapplication/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!"
}

注意:POST 要求中納入的 replyText 最多可包含 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 個

如果應用程式需要擷取或回覆的資料量超過配額所允許的數量,請提出要求,提高應用程式配額。