Obiettivi per i giochi Android

Questa guida mostra come utilizzare le API degli obiettivi in un'app per Android per sbloccare e visualizzare gli obiettivi nel 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 essere utile esaminare i concetti di gioco degli obiettivi.

Prima di iniziare a scrivere codice utilizzando l'API degli obiettivi:

• Segui le istruzioni per installare e configurare l'app in modo che utilizzi i servizi per i giochi di Google Play nella guida Configura l'SDK Google Play Services.

• Definisci gli obiettivi che vuoi che il tuo gioco sblocchi o visualizzi seguendo le istruzioni nella guida di Google Play Console.

• Scarica e rivedi gli esempi di codice degli obiettivi nella pagina degli esempi di Android.

• Fai pratica con i consigli descritti nella lista di controllo della qualità.

Ottenere un client degli obiettivi

Per iniziare a utilizzare l'API degli obiettivi, il tuo gioco deve prima ottenere un AchievementsClient oggetto. Puoi ottenerlo chiamando il Games.getAchievementClient() metodo e passando l'attività.

Sbloccare gli obiettivi

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

Il seguente snippet di codice mostra come l'app può sbloccare gli obiettivi:

PlayGames.getAchievementsClient(this).unlock(getString(R.string.my_achievement_id));

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

Il seguente snippet di codice mostra come l'app può incrementare l'obiettivo del giocatore:

PlayGames.getAchievementsClient(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 quando raggiunge il numero di passaggi richiesto.

Una buona pratica è 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 gli obiettivi, assicurati di seguire anche queste best practice per evitare di superare la quota dell'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 l'app può visualizzare l'interfaccia utente predefinita degli obiettivi. Nello snippet, RC_ACHIEVEMENT_UI è un numero intero arbitrario che il gioco utilizza come codice della 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);
        }
      });
}

L'immagine seguente mostra un esempio dell'interfaccia utente predefinita degli obiettivi.

La riga Suggeriti mostra l'obiettivo rivelato più comune, ovvero quello che il giocatore non ha ancora sbloccato, ma che la percentuale più alta di altri giocatori ha sbloccato.