回覆評論

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

Reply to Review API 只能讓您存取正式版應用程式的意見回饋。如果您想查看 Alpha 版或 Beta 版應用程式的意見回饋，請改用 Google Play 管理中心。另請注意，這個 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。

comments

這份清單包含使用者對應用程式的意見回饋。如果這則評論包含標題，則標題和評論內文都會顯示在 text 元素中，且標題和內文會以 Tab 字元分隔。lastModified 元素會指出使用者最近一次提交評論的時間。

如果你已回覆這則評論，你的意見回饋會顯示在留言清單的第二個元素。

starRating

使用者對您應用程式的評估，以 1 到 5 分表示。5 分表示使用者對您的應用程式非常滿意。

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

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

注意：您只能擷取使用者在過去一週內建立或修改的評論。如要擷取應用程式自推出以來的所有評論，您可以使用 Google Play 管理中心將評論下載為 CSV 檔案。

以下 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 方法擷取個別評論。您提供的網址與擷取一組評論時使用的網址相同，但您也會加入要查看的評論所對應的 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-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!"
}

注意：您在 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 要求 (用於回覆評論)：每日 2000 次

如果應用程式需要擷取或回覆的評論數量超出配額，請提出要求，調高應用程式的配額。