Obiettivi per i 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à.

Ottenere un client per gli obiettivi

Per iniziare a utilizzare l'API Achievements, il tuo gioco deve prima ottenere un oggetto AchievementsClient. Per farlo, puoi chiamare il metodo Games.getAchievementClient() e passare l'attività.

Sbloccare obiettivi

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

Il seguente snippet di codice mostra come la tua app può sbloccare i traguardi:

PlayGames.getAchievementsClient(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:

PlayGames.getAchievementsClient(this).increment(getString(R.string.my_achievement_id), 1);

Non devi scrivere codice aggiuntivo per sbloccare l'obiettivo. Google Play Services per i giochi sblocca automaticamente l'obiettivo quando viene raggiunto il numero di passaggi richiesto.

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 risultati, assicurati di seguire anche queste best practice per evitare di superare la quota dell'API.

Visualizzare gli obiettivi

Per mostrare i risultati di un giocatore, chiama AchievementsClient.getAchievementsIntent() per ottenere un Intent per creare l'interfaccia utente predefinita dei risultati. Il gioco può quindi visualizzare l'interfaccia utente chiamando startActivityForResult.

Il seguente snippet di codice mostra come la tua app può visualizzare l'interfaccia utente predefinita dei traguardi. Nello snippet, RC_ACHIEVEMENT_UI è un numero intero произвольный utilizzato dal gioco come codice richiesta.

private static final int RC_ACHIEVEMENT_UI = 9003;

private void showAchievements() {
  PlayGames.getAchievementsClient(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.