Trả lời bài đánh giá

API Trả lời bài đánh giá dành cho nhà phát triển trên Google Play cho phép bạn xem phản hồi của người dùng về ứng dụng và trả lời phản hồi này. Bạn có thể sử dụng API này để tương tác trực tiếp với người dùng trong bộ công cụ hỗ trợ khách hàng hiện tại, chẳng hạn như hệ thống CRM.

Reply to Reviews API chỉ cho phép bạn truy cập ý kiến phản hồi cho các phiên bản phát hành công khai của ứng dụng. Nếu bạn muốn xem ý kiến phản hồi về các phiên bản alpha hoặc beta của ứng dụng, hãy sử dụng Google Play Console. Ngoài ra, xin lưu ý rằng API chỉ cho thấy các bài đánh giá có nhận xét. Nếu người dùng xếp hạng ứng dụng của bạn nhưng không đưa ra nhận xét, thì API không thể truy cập vào phản hồi của họ.

Nhận quyền truy cập

Để làm việc với API Trả lời bài đánh giá, bạn cần uỷ quyền bằng cách sử dụng ứng dụng OAuth hoặc tài khoản dịch vụ. Nếu bạn đang sử dụng tài khoản dịch vụ, hãy bật quyền "Trả lời bài đánh giá" trong tài khoản này. Để biết thêm thông tin về cách thiết lập quyền truy cập được uỷ quyền vào API này, hãy xem phần Thiết lập ứng dụng truy cập API.

Truy xuất bài đánh giá

Khi sử dụng Reply to Reviews API, bạn có thể truy xuất danh sách tất cả các bài đánh giá gần đây cho ứng dụng hoặc bạn có thể xem từng bài đánh giá.

Truy xuất một nhóm bài đánh giá

Sử dụng phương thức GET để yêu cầu danh sách bài đánh giá cho ứng dụng. Trong yêu cầu, hãy bao gồm tên gói đủ điều kiện cho ứng dụng (chẳng hạn như com.google.android.apps.maps) và mã thông báo uỷ quyền bạn nhận được khi có được quyền truy cập vào API.

GET https://www.googleapis.com/androidpublisher/v3/applications/your_package_name/reviews?
access_token=your_auth_token

Phản hồi là một chuỗi JSON chứa danh sách các bài đánh giá cho ứng dụng của bạn. Kết quả đầu tiên trong danh sách này cho thấy bình luận của người dùng được tạo hoặc sửa đổi gần đây nhất.

Trong ví dụ sau, bài đánh giá đầu tiên cho thấy siêu dữ liệu xuất hiện trong tất cả các kết quả, còn bài đánh giá thứ hai chỉ hiển thị siêu dữ liệu xuất hiện trong một số kết quả:

{
  "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"
  }
}

Mỗi kết quả đều có siêu dữ liệu sau đây:

reviewId
Xác định duy nhất bài đánh giá này. Thuộc tính này cũng cho biết bài đánh giá của một người dùng cụ thể, vì người dùng chỉ có thể viết một bài đánh giá cho một ứng dụng cụ thể.
authorName

Tên của người dùng viết bài đánh giá.

Lưu ý: Trong một số ít trường hợp, authorName có thể không xuất hiện trong một kết quả nhất định.

comments

Danh sách chứa ý kiến phản hồi của người dùng về ứng dụng. Nếu bài đánh giá này có tiêu đề, thì tiêu đề này và văn bản nội dung của bài đánh giá sẽ xuất hiện trong phần tử text, đồng thời một ký tự thẻ phân tách tiêu đề và văn bản nội dung. Phần tử lastModified cho biết thời điểm người dùng gửi bài đánh giá gần đây nhất.

Nếu bạn đã trả lời bài đánh giá này, thì ý kiến phản hồi của bạn sẽ xuất hiện dưới dạng thành phần thứ hai trong danh sách bình luận.

starRating

Đánh giá của người dùng về ứng dụng của bạn theo thang điểm từ 1 đến 5. Điểm 5 cho biết người dùng rất hài lòng với ứng dụng của bạn.

Theo mặc định, 10 bài đánh giá sẽ xuất hiện trên mỗi trang. Bạn có thể cho thấy tối đa 100 bài đánh giá trên mỗi trang bằng cách đặt tham số maxResults trong yêu cầu.

Nếu danh sách bài đánh giá tiếp tục xuất hiện trên một trang khác, thì API sẽ bao gồm phần tử tokenPagination trong phản hồi. Khi yêu cầu trang đánh giá tiếp theo, hãy thêm phần tử token. Đặt giá trị của phần tử này thành giá trị nextPageToken xuất hiện trong phản hồi ban đầu.

Lưu ý: Bạn chỉ có thể truy xuất các bài đánh giá mà người dùng đã tạo hoặc sửa đổi trong tuần trước. Nếu muốn truy xuất tất cả bài đánh giá cho ứng dụng của mình kể từ đầu, bạn có thể tải bài đánh giá xuống dưới dạng tệp CSV bằng cách sử dụng Google Play Console.

Ví dụ sau đây về yêu cầu GET hiển thị trang bài đánh giá tiếp theo. Yêu cầu này giả định rằng trang bài đánh giá hiện tại (như hiển thị trong phản hồi yêu cầu trước đó) chứa giá trị nextPageToken"12334566". Yêu cầu này cũng cho biết rằng trang tiếp theo sẽ hiển thị tối đa 50 bài đánh giá.

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

Truy xuất từng bài đánh giá

Bạn cũng có thể sử dụng phương thức GET để truy xuất từng bài đánh giá. Bạn cung cấp URL giống như URL dùng để truy xuất một nhóm bài đánh giá, ngoại trừ việc bạn cũng thêm review_id tương ứng với bài đánh giá mà bạn muốn thấy:

GET https://www.googleapis.com/androidpublisher/v3/applications/your_package_name/reviews/
review_id?access_token=your_auth_token

Phản hồi tương ứng là một chuỗi JSON chứa nội dung và siêu dữ liệu cho một bài đánh giá:

{
  "reviewId": "87654321",
  "authorName": "Joan Smith",
  "comments": [
    {
      "userComment": {
        "text": "This app is awesome!",
        "lastModified": {
          "seconds": "1452114723",
          "nanos": 913000000
        },
        "starRating": 5
      }
    }
  ]
}

Dịch văn bản đánh giá

Văn bản đánh giá có thể được dịch tự động trước khi được trả về từ API bài đánh giá. Khi truy xuất một danh sách các bài đánh giá hoặc một bài đánh giá, hãy thêm tham số translationLanguage vào truy vấn. Ví dụ:

GET https://www.googleapis.com/androidpublisher/v3/applications/your_package_name/reviews?
access_token=your_auth_token&translationLanguage=en

Tham số translationLanguage có thể chỉ định một ngôn ngữ có hoặc không có quốc gia. Ví dụ: cả "en" và "en_GB" đều hợp lệ.

Nếu bạn chỉ định ngôn ngữ dịch khác với văn bản gốc, hệ thống sẽ trả về văn bản đã dịch trong thuộc tính text và văn bản gốc trong thuộc tính originalText. Ví dụ:

    {
      "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!"
          }
        }
      ]
    }

Trả lời bài đánh giá

Bạn cũng có thể tương tác với người dùng ứng dụng bằng cách trả lời bài đánh giá của họ. Sau khi bạn gửi câu trả lời, người dùng sẽ nhận được thông báo cho biết rằng bạn đã trả lời ý kiến phản hồi của họ.

Chúng tôi không khuyến khích sử dụng câu trả lời tự động cho các bài đánh giá, vì chúng tôi sẽ cập nhật các câu trả lời đó theo cách thủ công sau này. Ngoài ra, mặc dù bạn có thể trả lời bài đánh giá bao nhiêu lần tuỳ thích, nhưng người dùng chỉ nhận được thông báo sau lần đầu tiên bạn trả lời bài đánh giá đã tạo hoặc sửa đổi. Bảng sau đây minh hoạ cách người dùng nhận được thông báo trong quá trình bạn tương tác với họ:

Tương tác người dùng – nhà phát triển Đã gửi thông báo cho người dùng?
Người dùng viết bài đánh giá; nhà phát triển gửi câu trả lời
Nội dung cập nhật của nhà phát triển trả lời bài đánh giá ban đầu Không
Đánh giá nội dung cập nhật của người dùng; trả lời nội dung cập nhật của nhà phát triển

Lưu ý: Vì câu trả lời của bạn cho các bài đánh giá xuất hiện công khai trên trang cửa hàng ứng dụng, bạn không nên đưa vào thông tin nhạy cảm về người dùng khi viết các câu trả lời này.

Để gửi câu trả lời cho bài đánh giá của người dùng, hãy sử dụng phương thức POST. Trong yêu cầu của bạn, hãy cho biết Content-Typeapplication/json và bao gồm một tài liệu JSON chứa câu trả lời của bạn:

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!"
}

Lưu ý: replyText mà bạn đưa vào yêu cầu POST có thể chứa tối đa 350 ký tự. Bạn nên sử dụng văn bản thuần tuý trong thư trả lời của mình; các thẻ HTML có định dạng hợp lệ sẽ bị xoá và không được tính vào số ký tự của câu trả lời. Tuy nhiên, nội dung mà bạn đặt bên trong các thẻ HTML được định dạng tốt sẽ được giữ nguyên.

Nếu yêu cầu của bạn thành công, bạn sẽ nhận được chuỗi JSON sau đây dưới dạng phản hồi. Phần tử lastEdited cho biết thời điểm API ghi lại câu trả lời của bạn cho bài đánh giá của người dùng.

{
  "result": {
    "replyText": "Thanks for your feedback!",
    "lastEdited": {
      "seconds": "1453978803",
      "nanos": 796000000
    }
  }
}

Tuy nhiên, nếu yêu cầu POST của bạn không hợp lệ, phản hồi sẽ hiển thị một trong các mã lỗi sau:

400 Bad Reply Request
replyText quá dài hoặc bị thiếu.
404 Not Found
Bài đánh giá có review_id cụ thể không tồn tại.

Hạn mức

Để thể hiện thiện chí với các nhà phát triển khác, Reply to Reviews API có thực thi một số nguyên tắc. Các hạn mức này được áp dụng riêng cho từng ứng dụng:

  • GET yêu cầu (để truy xuất danh sách các bài đánh giá và từng bài đánh giá) – 200 mỗi giờ

  • POST yêu cầu (để trả lời bài đánh giá) – 2000 mỗi ngày

Nếu ứng dụng của bạn cần truy xuất hoặc trả lời một lượng lớn bài đánh giá hơn mức cho phép này, hãy gửi yêu cầu để tăng hạn mức của ứng dụng.