Classifiche nei giochi Android

Questa guida mostra come utilizzare le API leaderboard in un'app per Android per creare classifiche visive, registrare il punteggio di un giocatore e confrontare il punteggio rispetto al punteggio delle sessioni di gioco precedenti del giocatore. Puoi trovare le API in com.google.android.gms.games e com.google.android.gms.games.leaderboards pacchetti.

Prima di iniziare

Se non l'hai ancora fatto, potrebbe essere utile consultare il concetti dei giochi nelle classifiche.

Prima di iniziare a programmare con le API leaderboard:

• Segui le istruzioni per installare e configurare l'app e usarla Servizi per i giochi di Google Play in Guida alla configurazione dell'SDK Google Play Services.

• Definisci le classifiche che vuoi che vengano visualizzate o aggiornate dal tuo gioco seguendo le istruzioni riportate nel Guida di Google Play Console.

• Scarica ed esamina gli esempi di codice delle classifiche nella Pagina di esempio Android su GiHub.

• Acquisisci familiarità con i consigli descritti in Elenco di controllo della qualità.

Ottieni il client leaderboard

Per iniziare a utilizzare l'API leaderboard, il gioco deve prima ottenere un oggetto LeaderboardsClient. Puoi farlo chiamando il metodo Games.getLeadeboardsClient() e passando il valore-chiave attività.

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

Aggiornare il punteggio del giocatore

Quando il punteggio del giocatore cambia (ad esempio, quando il giocatore finisce la partita), i tuoi può aggiornare il proprio punteggio in classifica chiamando LeaderboardsClient.submitScore(), e passando l'ID della classifica e il valore del punteggio non elaborato.

Il seguente snippet di codice mostra in che modo l'app può aggiornare il punteggio del giocatore:

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

È buona norma definire l'ID classifica nel file strings.xml, quindi il tuo gioco può fare riferimento alle classifiche in base all'ID risorsa. Quando effettui chiamate a aggiorna e carica i punteggi dei giocatori, segui anche queste best practice per evitare di superare la quota API.

Visualizzare una classifica

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

Il seguente snippet di codice mostra in che modo l'app può aggiornare il punteggio del giocatore. Nella snippet di codice, RC_LEADERBOARD_UI è un numero intero arbitrario per il codice di 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. Un esempio delle metriche predefinite di seguito è mostrata l'interfaccia utente della classifica.