Statistiche dei giocatori nei giochi per Android

A seguito del ritiro dell'API Google Sign-In, rimuoveremo l'SDK v1 per i giochi nel 2026. Dopo febbraio 2025, non potrai pubblicare su Google Play titoli che sono stati integrati di recente con l'SDK v1 per i giochi. Ti consigliamo di utilizzare l'SDK v2 per i giochi.
Anche se i titoli esistenti con le precedenti integrazioni di giochi v1 continueranno a funzionare per un paio di anni, ti consigliamo di eseguire la migrazione alla v2 a partire da giugno 2025.
Questa guida riguarda l'utilizzo dell'SDK v1 dei servizi per i giochi di Play. Per informazioni sull'ultima versione dell'SDK, consulta la documentazione della versione 2.

L'API Player Stats ti consente di personalizzare le esperienze di gioco in base a segmenti specifici di giocatori e alle diverse fasi del ciclo di vita del giocatore. Puoi creare esperienze personalizzate per ogni segmento di giocatori in base al loro avanzamento, alla spesa e al coinvolgimento. Ad esempio, puoi utilizzare questa API per intraprendere azioni proattive per incoraggiare un giocatore meno attivo a interagire nuovamente con il tuo gioco, ad esempio mostrando e promuovendo nuovi elementi di gioco quando il giocatore accede.

Questa guida mostra come utilizzare l'API delle statistiche dei giocatori nei giochi utilizzando i servizi per i giochi di Google Play. Le API sono disponibili nei pacchetti com.google.android.gms.games.stats e com.google.android.gms.games.

Prima di iniziare

Prima di iniziare a utilizzare l'API delle statistiche dei giocatori:

• Scarica e rivedi l'esempio di codice.
• Acquisisci familiarità con i consigli descritti nella lista di controllo della qualità.

Scarica il client delle statistiche giocatore

Per iniziare a utilizzare l'API delle statistiche dei giocatori, il tuo gioco deve prima ottenere un oggetto PlayerStatsClient. Per farlo, chiama il metodo Games.getPlayerStatsClient() e passa l'attività e l'GoogleSignInAccount per il giocatore attuale. Per scoprire come recuperare le informazioni dell'account giocatore, consulta la sezione Accesso nei giochi per Android.

Nozioni di base sulle statistiche giocatore

Puoi utilizzare l'API delle statistiche dei giocatori per recuperare i dati sull'attività in-game di un giocatore. I tipi di dati dei giocatori che puoi recuperare includono:

• Durata media della sessione: la durata media della sessione del giocatore in minuti. La durata della sessione è determinata dal periodo di tempo in cui un giocatore ha eseguito l'accesso ai servizi per i giochi di Google Play.

• Giorni dall'ultima partita: il numero approssimativo di giorni dall'ultima partita del giocatore.

• Numero di acquisti: il numero approssimativo di acquisti in-app per il giocatore.

• Numero di sessioni: il numero approssimativo di sessioni del giocatore. Le sessioni sono determinate dal numero di volte in cui un giocatore accede ai servizi per i giochi di Google Play.

• Percentile sessione: l'approssimazione del percentile delle sessioni per il giocatore, espresso come valore decimale compreso tra 0 e 1 inclusi. Questo valore indica il numero di sessioni giocate dal giocatore attuale rispetto al resto della base di giocatori di questo gioco. Numeri più alti indicano che questo giocatore ha giocato più sessioni.

• Percentile di spesa: il percentile di spesa approssimativo del giocatore, espresso come valore decimale compreso tra 0 e 1 inclusi. Questo valore indica quanto ha speso il giocatore attuale rispetto al resto della base di giocatori di questo gioco. Numeri più alti indicano che questo giocatore ha speso di più.

I seguenti tipi di dati del giocatore sono ritirati e restituiscono sempre una costante di valore non impostato:

Recuperare i dati delle statistiche giocatore

Per recuperare i dati delle statistiche giocatore per il giocatore attualmente connesso:

1. Chiama il metodo PlayerStatsClient.loadPlayerStats().
2. Se la chiamata ha esito positivo, Google Play Games Services restituisce un oggetto Task che carica in modo asincrono un oggetto PlayerStats. Utilizza i metodi di questo oggetto per recuperare i dati sulle attività del giocatore che ha eseguito l'accesso nella tua app.

Ecco un esempio:

public void checkPlayerStats() {
  Games.getPlayerStatsClient(this, GoogleSignIn.getLastSignedInAccount(this))
      .loadPlayerStats(true)
      .addOnCompleteListener(new OnCompleteListener<AnnotatedData<PlayerStats>>() {
        @Override
        public void onComplete(@NonNull Task<AnnotatedData<PlayerStats>> task) {
          if (task.isSuccessful()) {
            // Check for cached data.
            if (task.getResult().isStale()) {
              Log.d(TAG, "using cached data");
            }
            PlayerStats stats = task.getResult().get();
            if (stats != null) {
              Log.d(TAG, "Player stats loaded");
              if (stats.getDaysSinceLastPlayed() > 7) {
                Log.d(TAG, "It's been longer than a week");
              }
              if (stats.getNumberOfSessions() > 1000) {
                Log.d(TAG, "Veteran player");
              }
              if (stats.getChurnProbability() == 1) {
                Log.d(TAG, "Player is at high risk of churn");
              }
            }
          } else {
            int status = CommonStatusCodes.DEVELOPER_ERROR;
            if (task.getException() instanceof ApiException) {
              status = ((ApiException) task.getException()).getStatusCode();
            }
            Log.d(TAG, "Failed to fetch Stats Data status: "
                + status + ": " + task.getException());
          }
        }
      });
}

Suggerimenti per l'utilizzo dei dati delle statistiche sui giocatori

L'API Play Stats ti consente di identificare facilmente vari tipi di giocatori in base al loro coinvolgimento e al loro comportamento di spesa e di applicare strategie appropriate per migliorare la loro esperienza di gioco.

La tabella seguente elenca alcuni segmenti di giocatori di esempio e le strategie di coinvolgimento consigliate: