API Trả lời bài đánh giá của 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 của mình và trả lời ý kiến 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.
API Trả lời bài đánh giá cho phép bạn chỉ truy cập vào 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 phản hồi về 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ỉ hiển thị những bài đánh giá có cá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 cung cấp nhận xét thì API không thể truy cập phản hồi của họ.
Có được quyền truy cập
Để sử dụng API Trả lời bài đánh giá, bạn phải cung cấp thông tin uỷ quyền bằng ứng dụng OAuth hoặc tài khoản dịch vụ. Nếu đ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 API Trả lời bài đánh giá, bạn có thể truy xuất danh sách tất cả các bài đánh giá gần đây về ứng dụng của mình hoặc xem từng bài đánh giá riêng lẻ.
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 các bài đánh giá cho ứng dụng của bạn. Trong yêu cầu, hãy thêm tên gói đủ điều kiện cho ứng dụng của bạn (chẳng hạn như com.google.android.apps.maps) và mã uỷ quyền mà bạn nhận được khi được cấp 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á về ứng dụng của bạn. Kết quả đầu tiên trong danh sách cho thấy bình luận gần đây nhất của người dùng hoặc bình luận đã được sửa đổi.
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ả kết quả, còn bài đánh giá thứ hai cho thấy siêu dữ liệu chỉ 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:
- reviewId
- Xác định duy nhất bài đánh giá này. Chỉ số 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, biểu tượng
authorNamecó thể không xuất hiện trong một kết quả nhất định.- comments
Một danh sách bao gồm ý 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ì cả tiêu đề và nội dung bài đánh giá đều xuất hiện trong phần tử
text, đồng thời ký tự tab sẽ phân tách tiêu đề và nội dung. Phần tửlastModifiedcho biết thời điểm gần đây nhất mà người dùng gửi bài đánh giá.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 phần tử 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ể hiển thị 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 của mình.
Nếu danh sách bài đánh giá tiếp tục trên một trang khác, API sẽ thêm một phần tử tokenPagination vào phản hồi. Khi yêu cầu trang tiếp theo của bài đánh giá, 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 những bài đánh giá mà người dùng đã tạo hoặc sửa đổi trong tuần qua. Nếu muốn truy xuất tất cả bài đánh giá về ứng dụng của mình kể từ khi bắt đầu, bạn có thể tải bài đánh giá xuống dưới dạng tệp CSV bằng Google Play Console.
Ví dụ sau đây về một yêu cầu GET sẽ hiển thị trang tiếp theo của các bài đánh giá. Yêu cầu này giả định rằng trang đánh giá hiện tại (như trong phản hồi của yêu cầu trước) chứa giá trị nextPageToken là "12334566". Yêu cầu này cũng cho biết 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 một bài đánh giá riêng lẻ
Bạn cũng có thể dùng phương thức GET để truy xuất từng bài đánh giá. Bạn cung cấp cùng một URL 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 xem:
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á duy nhất:
{
"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 đánh giá. Khi truy xuất danh sách bài đánh giá hoặc một bài đánh giá duy nhất, 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 một 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 bạn đã phản hồi ý kiến phản hồi của họ.
Chúng tôi không khuyến khích việc sử dụng tính năng trả lời tự động cho bài đánh giá với mục đích cập nhật những câu trả lời đó theo cách thủ công vào lúc khác. Ngoài ra, mặc dù bạn có thể trả lời một 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 một bài đánh giá đã được tạo hoặc sửa đổi. Bảng sau đây minh hoạ cách người dùng được thông báo trong quá trình bạn tương tác với họ:
| Tương tác giữa người dùng và nhà phát triển | Người dùng có nhận được thông báo không? |
|---|---|
| Người dùng viết bài đánh giá; nhà phát triển gửi câu trả lời | Có |
| Phản hồi của nhà phát triển đối với bài đánh giá ban đầu | Không |
| Người dùng cập nhật bài đánh giá; nhà phát triển cập nhật câu trả lời | Có |
Lưu ý: Vì câu trả lời của bạn cho bài đánh giá sẽ xuất hiện công khai trên trang cửa hàng ứng dụng, nên bạn không được thêm thông tin nhạy cảm về người dùng khi viết những 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 rằng Content-Type là application/json và thê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 câu 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ự cho câu trả lời của bạn. Tuy nhiên, nội dung mà bạn đặt bên trong các thẻ HTML có định dạng hợp lệ 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ệ, thì phản hồi sẽ hiển thị một trong các mã lỗi sau đây:
400 Bad Reply RequestreplyTextquá dài hoặc bị thiếu.404 Not Found- Bài đánh giá có
review_idđã cho 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ó áp dụng một số hạn mức. Các hạn mức này được thực thi riêng theo từng ứng dụng:
GETyêu cầu (để truy xuất danh sách bài đánh giá và từng bài đánh giá) – 200 yêu cầu mỗi giờPOSTyêu cầu (để trả lời bài đánh giá) – 2.000 yêu cầu mỗi ngày
Nếu ứng dụng của bạn cần truy xuất hoặc trả lời nhiều đánh giá hơn mức hạn ngạch này cho phép, hãy gửi yêu cầu để tăng hạn ngạch của ứng dụng.