Classifiche nei giochi Android

Questa guida illustra come utilizzare le API di classifiche in un'app per Android per creare classifiche visive, registrare il punteggio di un giocatore e confrontarlo con il punteggio 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, ti consigliamo di consultare 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 Configurare l'SDK Google Play Services.

• Definisci le classifiche che vuoi che il tuo gioco mostri o aggiorni seguendo le istruzioni riportate nella guida di Google Play Console.

• Scarica ed esamina gli esempi di codice delle classifiche nella pagina degli esempi per Android su GitHub.

• Acquisisci familiarità con i consigli descritti nel Controllo qualità.

Scarica il client per le classifiche

Per iniziare a utilizzare l'API Leaderboard, il tuo gioco deve prima ottenere un oggetto LeaderboardsClient. Per farlo, puoi chiamare il metodo PlayGames.getLeadeboardsClient() e passare l'attività.

Aggiornare il punteggio del giocatore

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

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

PlayGames.getLeaderboardsClient(this)
    .submitScore(getString(R.string.leaderboard_id), 1337);

Una buona prassi è definire l'ID classifica nel file strings.xml, in modo che il tuo 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 API.

Visualizzare una classifica

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

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

private static final int RC_LEADERBOARD_UI = 9004;

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

Anche se non viene restituito alcun risultato, devi utilizzare startActivityForResult in modo che l'API possa ottenere l'identità del pacchetto chiamante. Di seguito è riportato un esempio della UI della classifica predefinita.