Classifiche nei giochi Android

A seguito del ritiro dell'API Google Sign-In, nel 2026 rimuoveremo l'SDK v1 per i giochi. 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 integrati in precedenza con l'SDK v1 per i giochi continueranno a funzionare per un paio di anni, ti consigliamo di eseguire la migrazione all'SDK v2 a partire da giugno 2025.
Questa guida riguarda l'utilizzo dell'SDK Play Games Services v1. Per informazioni sull'ultima versione dell'SDK, consulta la documentazione per v2.

Questa guida mostra come utilizzare le API delle classifiche in un'app per Android per creare classifiche visive, registrare il punteggio di un giocatore e confrontarlo con il punteggio del giocatore delle sessioni di gioco precedenti. Le API sono disponibili nei pacchetti com.google.android.gms.games e com.google.android.gms.games.leaderboards.

Prima di iniziare

Se non l'hai ancora fatto, potrebbe esserti utile rivedere i concetti di gioco delle classifiche.

Prima di iniziare a scrivere codice utilizzando le API delle classifiche:

• Segui le istruzioni per installare e configurare l'app in modo che utilizzi i servizi per i giochi di Google Play nella guida Configura l'SDK Google Play Services.
• Definisci le classifiche che vuoi che il tuo gioco mostri o aggiorni seguendo le istruzioni della guida di Google Play Console.
• Scarica e rivedi gli esempi di codice delle classifiche nella pagina degli esempi di Android.
• Acquisisci familiarità con i consigli descritti nella lista di controllo della qualità.

Ottieni il client delle classifiche

Per iniziare a utilizzare l'API delle classifiche, il tuo gioco deve prima ottenere un oggetto LeaderboardsClient. Per farlo, chiama il metodo Games.getLeadeboardsClient() e passa l'attività e il parametro GoogleSignInAccount per il giocatore corrente. Per scoprire come recuperare le informazioni dell'account del giocatore, consulta la sezione Accedi ai giochi per Android.

Nota: la classe LeaderboardsClient utilizza la classe Task di Google Play Services per restituire i risultati in modo asincrono. Per saperne di più sull'utilizzo delle attività per gestire il lavoro in thread, consulta la Guida per gli sviluppatori dell'API Tasks.

Aggiorna il punteggio del giocatore

Quando il punteggio del giocatore cambia (ad esempio, quando completa il gioco), il tuo gioco può aggiornare il suo punteggio nella classifica chiamando LeaderboardsClient.submitScore(), e passando l'ID classifica e il valore del punteggio grezzo.

Il seguente snippet di codice mostra come la tua app può aggiornare il punteggio del giocatore:

Games.getLeaderboardsClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .submitScore(getString(R.string.leaderboard_id), 1337);

Una buona pratica è definire l'ID classifica nel file strings.xml, in modo che il gioco possa fare riferimento alle classifiche in base all'ID risorsa. Quando effettui chiamate per aggiornare e caricare i punteggi dei giocatori, assicurati di seguire anche queste best practice per evitare di superare la quota dell'API.

Visualizza una classifica

Per visualizzare la classifica, chiama LeaderboardsClient.getLeaderboardIntent() per ottenere un Intent per creare l'interfaccia utente predefinita della classifica. Il gioco può quindi visualizzare l'interfaccia utente chiamando startActivityForResult.

Il seguente snippet di codice mostra come la tua app può aggiornare il punteggio del giocatore. Nello snippet di codice, RC_LEADERBOARD_UI è un numero intero arbitrario per il codice della richiesta.

private static final int RC_LEADERBOARD_UI = 9004;

private void showLeaderboard() {
  Games.getLeaderboardsClient(this, GoogleSignIn.getLastSignedInAccount(this))
      .getLeaderboardIntent(getString(R.string.leaderboard_id))
      .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent intent) {
          startActivityForResult(intent, RC_LEADERBOARD_UI);
        }
      });
}

Tieni presente che, anche se non viene restituito alcun risultato, dobbiamo utilizzare startActivityForResult in modo che l'API possa ottenere l'identità del pacchetto chiamante. Di seguito è riportato un esempio dell'interfaccia utente predefinita della classifica.