Obiettivi nei giochi Android

Questa guida spiega come utilizzare le API di obiettivi in un'applicazione Android per sbloccare e visualizzare gli obiettivi nel tuo gioco. Le API sono disponibili nei pacchetti com.google.android.gms.games e com.google.android.gms.games.achievements.

Prima di iniziare

Se non l'hai ancora fatto, ti consigliamo di consultare i concetti di gioco per gli obiettivi.

Prima di iniziare a scrivere codice utilizzando l'API Achievements:

• 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 i traguardi che vuoi che il tuo gioco sblocchi o mostri seguendo le istruzioni riportate nella guida di Google Play Console.
• Scarica ed esamina gli esempi di codice per i traguardi nella pagina degli esempi per Android.
• Acquisisci familiarità con i consigli descritti nel Controllo qualità.

Acquisisci un cliente per gli obiettivi

Per iniziare a utilizzare l'API Achievements, il tuo gioco deve prima ottenere un oggetto AchievementsClient. Per farlo, chiama il metodo Games.getAchievementClient() e passa l'attività e il GoogleSignInAccount per il player corrente. Per scoprire come recuperare i dati dell'account del giocatore, consulta Accedere a Android Giochi.

Sbloccare obiettivi

Per sbloccare un obiettivo, chiama il metodo AchievementsClient.unlock() e invia l'ID obiettivo.

Il seguente snippet di codice mostra come la tua app può sbloccare gli obiettivi:

Games.getAchievementsClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .unlock(getString(R.string.my_achievement_id));

Se l'obiettivo è di tipo incrementale (ovvero sono necessari diversi passaggi per sbloccarlo), chiama AchievementsClient.increment().

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

Games.getAchievementsClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .increment(getString(R.string.my_achievement_id), 1);

Non devi scrivere codice aggiuntivo per sbloccare l'obiettivo. Google Play Services per i giochi lo sblocca automaticamente quando raggiunge il numero di passaggi richiesti.

Una buona prassi è definire gli ID degli obiettivi nel file strings.xml, in modo che il gioco possa fare riferimento agli obiettivi in base all'ID risorsa. Quando effettui chiamate per aggiornare e caricare i traguardi, assicurati di seguire anche queste best practice per evitare di superare la quota API.

Visualizzare gli obiettivi

Per mostrare gli obiettivi di un giocatore, chiama AchievementsClient.getAchievementsIntent() per ricevere un Intent e creare l'interfaccia utente predefinita degli obiettivi. Il gioco può quindi visualizzare la UI chiamando startActivityForResult.

Il seguente snippet di codice mostra come la tua app può visualizzare l'interfaccia utente predefinita dell'obiettivo. Nello snippet, RC_ACHIEVEMENT_UI è un numero intero arbitrario utilizzato dal gioco come codice richiesta.

private static final int RC_ACHIEVEMENT_UI = 9003;

private void showAchievements() {
  Games.getAchievementsClient(this, GoogleSignIn.getLastSignedInAccount(this))
      .getAchievementsIntent()
      .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent intent) {
          startActivityForResult(intent, RC_ACHIEVEMENT_UI);
        }
      });
}

Di seguito è riportato un esempio dell'interfaccia utente dei traguardi predefinita.