Obiettivi nei giochi Android

A seguito del ritiro dell'API Google Sign-In, rimuoveremo l'SDK v1 per i giochi nel 2026. 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 della versione 2.

Questa guida mostra come utilizzare le API Achievements 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, potrebbe esserti utile rivedere i concetti di gioco degli obiettivi.

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

Ottenere un client di 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 parametro GoogleSignInAccount per il giocatore corrente. Per scoprire come recuperare le informazioni dell'account del giocatore, consulta la sezione Accesso nei giochi per Android.

Sbloccare obiettivi

Per sbloccare un obiettivo, chiama il metodo AchievementsClient.unlock() e trasmetti l'ID dell'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ò incrementare l'obiettivo 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 Games Services lo sblocca automaticamente una volta raggiunto il numero di passaggi richiesto.

Una buona pratica è definire gli ID obiettivo 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 gli obiettivi, 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 ottenere un Intent per creare l'interfaccia utente predefinita degli obiettivi. 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 degli obiettivi. Nello snippet, RC_ACHIEVEMENT_UI è un numero intero arbitrario che il gioco utilizza come codice di 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 della UI predefinita degli obiettivi.