Erfolge für Android-Spiele

In diesem Leitfaden erfahren Sie, wie Sie die Erfolge-APIs in einer Android-App verwenden, um Erfolge in Ihrem Spiel freizuschalten und anzuzeigen. Die APIs befinden sich in den Paketen com.google.android.gms.games und com.google.android.gms.games.achievements.

Hinweis

Wir empfehlen Ihnen, sich mit den Konzepten für Erfolge vertraut zu machen, sofern Sie dies nicht schon getan haben.

Bevor Sie mit dem Programmieren mit den Erfolge-APIs beginnen, sollten Sie Folgendes tun:

• Folgen Sie der Anleitung zum Installieren und Einrichten Ihrer App für die Verwendung der Google Play Games-Dienste im Leitfaden Google Play-Dienste einrichten.

• Definieren Sie die Erfolge, die in Ihrem Spiel freigeschaltet oder angezeigt werden sollen, indem Sie dem Leitfaden für die Google Play Console folgen.

• Laden Sie die Codebeispiele für Erfolge auf der Seite mit Android-Beispielen herunter und sehen Sie sie sich an.

• Machen Sie sich mit den Empfehlungen der Qualitätscheckliste vertraut.

Erfolgsclient abrufen

Bevor Sie die Erfolge-APIs verwenden können, muss Ihr Spiel zuerst ein AchievementsClient-Objekt abrufen. Rufen Sie dazu die Methode Games.getAchievementClient() auf und übergeben Sie die Aktivität.

Erfolge freischalten

Rufen Sie die AchievementsClient.unlock() Methode auf und übergeben Sie die Erfolgs-ID, um einen Erfolg freizuschalten.

Das folgende Code-Snippet zeigt, wie Ihre App Erfolge freischalten kann:

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

Wenn der Erfolg vom Typ inkrementell ist (d. h., es sind mehrere Schritte erforderlich, um ihn freizuschalten), rufen Sie stattdessen AchievementsClient.increment() auf.

Das folgende Code-Snippet zeigt, wie Ihre App den Erfolgsfortschritt des Spielers inkrementieren kann:

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

Sie müssen keinen zusätzlichen Code schreiben, um den Erfolg freizuschalten. Die Google Play Games Services SDK schaltet den Erfolg automatisch frei, sobald die erforderliche Anzahl von Schritten erreicht ist.

Es empfiehlt sich, die Erfolgs-IDs in der Datei strings.xml zu definieren, damit Ihr Spiel über die Ressourcen-ID auf die Erfolge verweisen kann. Wenn Sie Aufrufe zum Aktualisieren und Laden von Erfolgen ausführen, sollten Sie auch diese Best Practices befolgen, um Ihr API Kontingent nicht zu überschreiten.

Erfolge anzeigen

Rufen Sie AchievementsClient.getAchievementsIntent() auf, um die Erfolge eines Spielers anzuzeigen und einen Intent zu erhalten, mit dem Sie die Standardbenutzeroberfläche für Erfolge erstellen können. Ihr Spiel kann dann die Benutzeroberfläche durch Aufrufen von startActivityForResult anzeigen.

Das folgende Code-Snippet zeigt, wie Ihre App die Standardbenutzeroberfläche für Erfolge anzeigen kann. Im Snippet ist RC_ACHIEVEMENT_UI eine beliebige Ganzzahl, die vom Spiel als Anfragecode verwendet wird.

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);
        }
      });
}

Das folgende Bild zeigt ein Beispiel für die Standardbenutzeroberfläche für Erfolge.

In der Zeile Vorgeschlagen wird der am häufigsten erreichte Erfolg angezeigt, den der Spieler noch nicht freigeschaltet hat.