A API Reply to Reviews do Google Play Developer permite conferir e responder ao feedback dos usuários do seu app. É possível usar essa API para interagir com os usuários diretamente no kit de ferramentas de suporte ao cliente, como um sistema de CRM.
A API Reply to Reviews permite acessar o feedback somente para as versões de produção do app. Se você quiser ver o feedback sobre as versões Alfa ou Beta do seu app, use o Google Play Console. Além disso, a API mostra somente as avaliações que incluem comentários. Se um usuário avaliar seu app, mas não comentar, o feedback dele não poderá ser acessado pela API.
Conseguir acesso
Para trabalhar com a API Reply to Reviews, é necessário conceder autorização usando um cliente OAuth ou uma conta de serviço. Se você estiver usando uma conta de serviço, ative a permissão "Responder a avaliações" nessa conta. Para saber mais sobre como estabelecer o acesso autorizado a essa API, confira Configurar clientes de acesso à API.
Recuperar avaliações
Com a API Reply to Reviews, é possível recuperar uma lista de todas as avaliações recentes do seu app ou ver uma avaliação individual.
Recuperar um conjunto de avaliações
Use o método GET para solicitar uma lista de avaliações do app. Na solicitação, inclua o nome do pacote totalmente qualificado do app, como com.google.android.apps.maps, e o token de autorização que você recebeu ao conseguir acesso à API.
GET https://www.googleapis.com/androidpublisher/v3/applications/your_package_name/reviews? access_token=your_auth_token
A resposta é uma string JSON que contém uma lista de avaliações do app. O primeiro resultado da lista mostra o comentário de usuário criado ou modificado mais recentemente.
No exemplo a seguir, a primeira avaliação mostra metadados que aparecem em todos os resultados, e a segunda mostra metadados que aparecem somente em alguns resultados:
{
"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"
}
}
Cada resultado inclui os seguintes metadados:
- reviewId
- Identifica a avaliação de modo exclusivo. Também indica a avaliação de um usuário específico, já que as pessoas podem escrever somente uma avaliação para cada app.
- authorName
O nome do usuário que escreve a avaliação.
Observação: em casos raros, o
authorNamepode não aparecer em um determinado resultado.- comments
Uma lista que inclui o feedback do usuário sobre o app. Se essa avaliação incluir um título, esse título e o corpo do texto da avaliação aparecerão no elemento
text, e um caractere de tabulação separará o título do texto. O elementolastModifiedindica a hora em que o usuário enviou a avaliação mais recente.Se você já respondeu a esta avaliação, seu feedback é exibido como o segundo elemento na lista de comentários.
- starRating
É a avaliação do usuário sobre seu app em uma escala de 1 a 5. Uma pontuação de 5 indica que o usuário está muito satisfeito com o app.
Por padrão, dez avaliações aparecem em cada página. É possível exibir até cem avaliações por página definindo o parâmetro maxResults na solicitação.
Se a lista de avaliações continuar em outra página, a API incluirá um elemento tokenPagination na resposta. Ao solicitar a próxima página de avaliações, inclua o elemento token. Defina o valor deste elemento como nextPageToken, que aparece na resposta original.
Observação: é possível recuperar somente as avaliações que os usuários criaram ou modificaram na última semana. Se quiser recuperar todas as avaliações do seu app desde o início, faça o download delas como um arquivo CSV usando o Google Play Console.
O exemplo a seguir de uma solicitação GET exibe a próxima página de avaliações. Essa solicitação presume que a página de avaliações atual (conforme mostrado na resposta da solicitação anterior) contém um valor nextPageToken de "12334566". A solicitação também indica que a próxima página precisa exibir até 50 avaliações.
GET https://www.googleapis.com/androidpublisher/v3/applications/your_package_name/reviews? access_token=your_auth_token&token=12334566&maxResults=50
Recuperar uma avaliação individual
Também é possível usar o método GET para recuperar uma avaliação individual. Você fornece o mesmo URL usado para recuperar um conjunto de avaliações, mas também inclui o review_id correspondente à avaliação que você quer consultar:
GET https://www.googleapis.com/androidpublisher/v3/applications/your_package_name/reviews/ review_id?access_token=your_auth_token
A resposta correspondente é uma string JSON que inclui conteúdo e metadados para uma única avaliação:
{
"reviewId": "87654321",
"authorName": "Joan Smith",
"comments": [
{
"userComment": {
"text": "This app is awesome!",
"lastModified": {
"seconds": "1452114723",
"nanos": 913000000
},
"starRating": 5
}
}
]
}
Traduzir textos de avaliação
O texto da avaliação pode ser traduzido automaticamente antes de ser retornado pela API de avaliações. Ao recuperar uma lista de avaliações ou uma única avaliação, adicione um parâmetro translationLanguage à consulta. Por exemplo:
GET https://www.googleapis.com/androidpublisher/v3/applications/your_package_name/reviews? access_token=your_auth_token&translationLanguage=en
O parâmetro translationLanguage pode especificar um idioma com ou sem país. Por exemplo, "en" e "en_GB" são válidos.
Se você especificar um idioma de tradução diferente do original, o sistema retornará o texto traduzido na propriedade text e o texto original na propriedade originalText. Veja um exemplo:
{
"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!"
}
}
]
}
Responder a avaliações
Também é possível interagir com os usuários do seu app respondendo às avaliações deles. Depois de enviar sua resposta, o usuário recebe uma notificação indicando que você respondeu ao feedback dele.
Não é recomendável usar respostas automáticas às avaliações, com a intenção de atualizá-las manualmente mais tarde. Além disso, embora seja possível responder a uma avaliação quantas vezes quiser, o usuário receberá uma notificação somente depois da primeira vez que você responder a uma avaliação criada ou modificada. A tabela a seguir ilustra como o usuário é notificado durante suas interações com ele:
| Interação entre usuário e desenvolvedor | A notificação foi enviada ao usuário? |
|---|---|
| O usuário escreve a avaliação, o desenvolvedor envia resposta. | Sim |
| O desenvolvedor atualiza a resposta à avaliação original. | Não |
| O usuário atualiza a avaliação, o desenvolvedor atualiza a resposta. | Sim |
Observação: como suas respostas às avaliações aparecem publicamente na página da loja, é importante que você não inclua informações confidenciais sobre os usuários ao escrevê-las.
Para enviar uma resposta à avaliação de um usuário, use o método POST. Na sua solicitação, indique que Content-Type é application/json e inclua um documento JSON que contenha sua resposta:
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!"
}
Observação: o replyText incluído na solicitação POST pode conter no máximo 350 caracteres. Use um texto simples na resposta. Tags HTML bem formadas são removidas e não são incluídas na contagem de caracteres da sua resposta. No entanto, o conteúdo que você coloca dentro de tags HTML bem formadas é preservado.
Caso sua solicitação seja bem-sucedida, você receberá a string JSON a seguir como resposta.
O elemento lastEdited indica a hora em que a API registra sua resposta à avaliação do usuário.
{
"result": {
"replyText": "Thanks for your feedback!",
"lastEdited": {
"seconds": "1453978803",
"nanos": 796000000
}
}
}
No entanto, se a solicitação POST for inválida, a resposta exibirá um dos seguintes códigos de erro:
400 Bad Reply Request- O
replyTexté muito longo ou está ausente. 404 Not Found- A avaliação com o
review_idfornecido não existe.
Cotas
Como uma cortesia para outros desenvolvedores, a API Reply to Reviews impõe diversas cotas. Essas cotas são aplicadas separadamente e por app:
Solicitações
GET(para recuperação de listas de avaliações e avaliações individuais): 200 por horaSolicitações
POST(para responder a avaliações): 2.000 por dia.
Caso seu app precise recuperar ou responder a um volume maior de avaliações do que o permitido pelas cotas, envie uma solicitação para aumentar a cota do app.