Rispondi alle recensioni

L'API Google Play Developer Reply to Reviews ti consente di visualizzare il feedback degli utenti relativi alla tua app e di rispondere a questo feedback. Puoi utilizzare questa API per interagire con gli utenti direttamente all'interno del tuo toolkit di assistenza clienti esistente, ad esempio un sistema CRM.

L'API Reply to Reviews ti consente di accedere ai feedback solo per le versioni di produzione della tua app. Se vuoi ricevere feedback sulle versioni alpha o beta della tua app, utilizza invece Google Play Console. Inoltre, tieni presente che l'API mostra solo le recensioni che includono commenti. Se un utente valuta la tua app ma non fornisce un commento, il suo feedback non è accessibile dall'API.

Ottenere l'accesso

Per utilizzare l'API Reply to Reviews, devi fornire l'autorizzazione utilizzando un client OAuth o un account di servizio. Se utilizzi un account di servizio, attiva l'autorizzazione "Risposta a recensioni" in questo account. Per ulteriori informazioni su come stabilire l'accesso autorizzato a questa API, consulta la pagina Configurare i client di accesso all'API.

Recupero di recensioni

Quando utilizzi l'API Reply to Reviews, puoi recuperare un elenco di tutte le recensioni recenti della tua app oppure visualizzare una singola recensione.

Recupero di un insieme di recensioni

Utilizza il metodo GET per richiedere un elenco di recensioni per la tua app. Nella richiesta, includi il nome completo del pacchetto dell'app, ad esempio com.google.android.apps.maps, e il token di autorizzazione che hai ricevuto quando ottieni l'accesso all'API.

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

La risposta è una stringa JSON che contiene un elenco di recensioni relative alla tua app. Il primo risultato nell'elenco mostra il commento dell'utente creato o modificato più di recente.

Nell'esempio seguente, la prima recensione mostra i metadati che appaiono in tutti i risultati, mentre la seconda mostra i metadati che appaiono solo in alcuni risultati:

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

Ogni risultato include i seguenti metadati:

reviewId
Identifica in modo univoco questa recensione. Indica inoltre la recensione specifica di un utente, dal momento che gli utenti possono scrivere una sola recensione per una determinata app.
authorName

Il nome dell'utente che scrive la recensione.

Nota: in rari casi, authorName potrebbe non comparire in un determinato risultato.

comments

Un elenco che include il feedback dell'utente sull'app. Se questa recensione include un titolo, questo e il corpo del testo della recensione vengono entrambi visualizzati nell'elemento text e il carattere della scheda separa il titolo e il corpo del testo. L'elemento lastModified indica l'ora in cui l'utente ha inviato più di recente la recensione.

Se hai già risposto a questa recensione, il tuo feedback viene visualizzato come secondo elemento nell'elenco dei commenti.

starRating

La valutazione degli utenti della tua app su una scala da 1 a 5. Un punteggio pari a 5 indica che l'utente è molto soddisfatto della tua app.

Per impostazione predefinita, in ogni pagina vengono visualizzate dieci recensioni. Puoi visualizzare fino a 100 recensioni per pagina impostando il parametro maxResults nella richiesta.

Se l'elenco delle recensioni continua su un'altra pagina, l'API include un elemento tokenPagination nella risposta. Quando richiedi la pagina successiva di recensioni, includi l'elemento token. Imposta il valore di questo elemento sul valore nextPageToken, che viene visualizzato nella risposta originale.

Nota: puoi recuperare solo le recensioni che gli utenti hanno creato o modificato nell'ultima settimana. Se vuoi recuperare tutte le recensioni relative alla tua app dall'inizio, puoi scaricare le recensioni come file CSV utilizzando Google Play Console.

Il seguente esempio di richiesta GET mostra la pagina successiva delle recensioni. Questa richiesta presuppone che la pagina corrente delle recensioni (come mostrato nella risposta alla richiesta precedente) contenga un valore nextPageToken pari a "12334566". La richiesta indica inoltre che nella pagina successiva devono essere mostrate fino a 50 recensioni.

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

Recupero di una singola recensione

Puoi anche utilizzare il metodo GET per recuperare una singola recensione. Devi fornire lo stesso URL utilizzato per recuperare un insieme di recensioni, ma devi includere anche il review_id corrispondente alla recensione che vuoi visualizzare:

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

La risposta corrispondente è una stringa JSON che include contenuti e metadati per una singola recensione:

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

Traduzione del testo della recensione

Il testo della recensione può essere tradotto automaticamente prima di essere restituito dall'API Recensioni. Quando recuperi un elenco di recensioni o una singola recensione, aggiungi un parametro translationLanguage alla query. Ad esempio:

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

Il parametro translationLanguage può specificare una lingua con o senza paese. Ad esempio, sia "en" che "en_GB" sono validi.

Se specifichi una lingua di traduzione diversa dal testo originale, il sistema restituisce il testo tradotto nella proprietà text e il testo originale nella proprietà originalText. Esempio:

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

Rispondere alle recensioni

Puoi anche interagire con gli utenti della tua app rispondendo alle loro recensioni. Dopo che invii la risposta, l'utente riceve una notifica in cui viene indicato che hai risposto al suo feedback.

Sconsigliamo l'utilizzo di risposte automatiche alle recensioni, con l'intento di aggiornarle manualmente in un secondo momento. Inoltre, anche se puoi rispondere a una recensione tutte le volte che vuoi, l'utente riceve una notifica solo dopo la prima risposta a una recensione creata o modificata. La seguente tabella illustra in che modo l'utente viene avvisato durante le interazioni con l'utente:

Interazione utente-sviluppatore Notifica inviata all'utente?
L'utente scrive la recensione; lo sviluppatore invia la risposta
Gli aggiornamenti dello sviluppatore rispondono alla recensione originale No
Recensione degli aggiornamenti utente; risposta agli aggiornamenti dello sviluppatore

Nota: poiché le risposte alle recensioni vengono visualizzate pubblicamente nella pagina dello store, è importante non includere informazioni sensibili sugli utenti quando scrivi queste risposte.

Per inviare una risposta alla recensione di un utente, utilizza il metodo POST. Nella richiesta, indica che Content-Type è application/json e includi un documento JSON che contenga la tua risposta:

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

Nota: il replyText che includi nella richiesta POST può contenere al massimo 350 caratteri. Nella risposta devi utilizzare testo normale; i tag HTML ben strutturati vengono rimossi e non sono inclusi nel conteggio dei caratteri della risposta. Tuttavia, i contenuti che inserisci all'interno di tag HTML con formato corretto vengono conservati.

Se la richiesta ha esito positivo, riceverai la seguente stringa JSON come risposta. L'elemento lastEdited indica il momento in cui l'API registra la tua risposta alla recensione dell'utente.

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

Se la richiesta POST non è valida, tuttavia, la risposta mostra uno dei seguenti codici di errore:

400 Bad Reply Request
Il campo replyText è troppo lungo o non è presente.
404 Not Found
La recensione con il valore review_id specificato non esiste.

Quote

A titolo di cortesia per altri sviluppatori, l'API Reply to Reviews prevede l'applicazione di diverse quote. Queste quote vengono applicate separatamente in base alle singole app:

  • Richieste GET (per recuperare elenchi di recensioni e singole recensioni): 200 all'ora

  • POST richieste (per rispondere alle recensioni): 2000 al giorno

Se la tua app deve recuperare o rispondere a un volume di recensioni maggiore di quello consentito da queste quote, invia una richiesta per aumentare la quota dell'app.