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 cho ứng dụng của bạn 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.
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 chính thức của ứng dụng. Nếu bạn muốn xem 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ỉ hiển thị các bài đánh giá có chứa 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 đó sẽ không thể phản hồi.
Nhận quyền truy cập
Để làm việc với API trả lời bài đánh giá, bạn cấp quyền bằng cách sử dụng ứng dụng khách 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 cấp 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 cấp phép vào API này, hãy xem nội dung Thiết lập ứng dụng truy cập API.
Đang 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ả bài đánh giá gần đây cho ứng dụng của mình hoặc có thể xem từng bài đánh giá.
Truy xuất tập hợp các bài đánh giá
Hãy 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 của bạn, hãy đưa vào 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ã thông báo uỷ quyền mà bạn nhận được khi lấy 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 bài đánh giá cho ứng dụng của bạn. Kết quả đầu tiên trong danh sách cho thấy nhận xét 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 hiển thị siêu dữ liệu xuất hiện trong tất cả kết quả và bài đánh giá thứ hai hiển thị 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ả bao gồm siêu dữ liệu sau:
- Id đánh giá
- Xác định riêng biệt bài đánh giá này. Điểm 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ể.
- Tên tác giả
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,
authorNamecó thể không xuất hiện trong một kết quả nhất định.- bình luận
Một danh sách bao gồm phản hồi của người dùng về ứng dụng. Nếu bài đánh giá này bao gồm tiêu đề, thì tiêu đề này và văn bản nội dung của bài đánh giá đều xuất hiện trong phần tử
textvà ký tự tab sẽ tách riêng tiêu đề và văn bản nội dung. Phần tửlastModifiedcho biết thời gian gần đây nhất mà người dùng gửi bài đánh giá.Nếu bạn đã phản hồi bài đánh giá này, ý 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 các nhận xét.
- saoĐiểm xếp hạng
Đánh giá của người dùng về thang điểm từ 1 đến 5. Điểm 5 cho biết rằng 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 thông số maxResults trong yêu cầu của bạn.
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 xem xét tiếp theo, hãy thêm phần tử token. Đặt giá trị của thành phần 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 bạn muốn truy xuất tất cả các bài đánh giá cho ứng dụng của mình ngay từ đầu thời gian, bạn có thể tải các 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 của yêu cầu GET 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 bài đánh giá hiện tại (như được thể hiện trong nội dung phản hồi của 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 có thể 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 bài đánh giá riêng lẻ
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 với URL được sử dụng để truy xuất tập hợp bài đánh giá, ngoại trừ việc bạn cũng bao gồ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á:
{
"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 danh sách 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 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. Sau đây là 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 phản hồi, người dùng sẽ nhận được thông báo cho biết bạn đã phản hồi.
Chúng tôi không khuyến khích sử dụng câu trả lời tự động cho bài đánh giá, với ý định cập nhật những câu trả lời đó sau này theo cách thủ công. Ngoài ra, mặc dù bạn có thể trả lời bài đánh giá bao nhiêu lần tùy 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á đã được 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 nhà phát triển người dùng | Thông báo đã được gửi tới 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 | Có |
| Nhà phát triển cập nhật phản hồi cho bài đánh giá gốc | Không |
| Xem lại bản cập nhật cho người dùng; câu trả lời cho bản cập nhật dành cho nhà phát triển | Có |
Lưu ý: Vì câu trả lời của bạn cho bài đánh giá xuất hiện công khai trên trang cửa hàng ứng dụng, nên điều quan trọng là bạn không được cung cấp thông tin nhạy cảm về người dùng khi bạn 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à bao gồm tài liệu JSON chứa nội dung trả lời:
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ác thẻ HTML có định dạng hợp lệ sẽ bị xoá và không được đưa vào số lượng ký tự trong câu trả lời. Tuy nhiên, nội dung mà bạn đặt bên trong các thẻ HTML được tạo đúng cách 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 phản hồ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 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
Để tôn trọng các nhà phát triển khác, API trả lời bài đánh giá thực thi một số hạn mức. Các hạn mức này được áp dụng riêng cho 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 mỗi giờPOSTyê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 số lượng bài đánh giá cao hơn so với hạn mức cho phép này, hãy gửi yêu cầu để tăng hạn mức ứng dụng của bạn.