Responder a avaliações

A API Reply to Reviews da Google Play Developer permite ver o feedback dos usuários do seu app e respondê-los. É 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 authorName pode 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 elemento lastModified indica 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 das avaliações

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 atualizaçã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_id fornecido 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): 60 por hora.

  • Solicitações POST (para responder a avaliações): 500 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.