Ereignisse in Android-Spielen

Nach der Einstellung der Google Sign-In API wird 2026 das games v1 SDK entfernt. Ab Februar 2025 können Sie bei Google Play keine Titel mehr veröffentlichen, die neu in games v1 SDK integriert wurden. Wir empfehlen, stattdessen das games v2 SDK zu verwenden.
Bestehende Titel mit den vorherigen games v1-Integrationen funktionieren zwar noch einige Jahre, aber wir empfehlen Ihnen, ab Juni 2025 zu v2 zu migrieren.
Dieser Leitfaden bezieht sich auf die Verwendung des Play Games-Dienste v1 SDK. Informationen zur neuesten SDK-Version finden Sie in der Dokumentation zu Version 2.

In diesem Leitfaden erfahren Sie, wie Sie mithilfe der von Google Play Games Services bereitgestellten Events APIs Gameplay-Daten von Spielern für die Spieleanalyse erfassen. Die APIs finden Sie unter com.google.android.gms.games.event und com.google.android.gms.games.

Hinweis

Wir empfehlen Ihnen, sich mit den Konzepten von Ereignissen in Spielen vertraut zu machen, sofern Sie dies nicht schon getan haben.

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

Events-Client abrufen

Bevor Sie die Events APIs verwenden können, muss Ihr Spiel zuerst ein EventsClient-Objekt abrufen. Rufen Sie dazu die Methode Games.getEventsClient() auf und übergeben Sie die Aktivität und die GoogleSignInAccount für den aktuellen Spieler. Informationen zum Abrufen der Spielerkontoinformationen finden Sie unter Anmelden in Android-Spielen.

Ereignisse einreichen

Sie können Code in Ihr Spiel einfügen, um die Google Play-Spieldienste zu benachrichtigen, wenn ein für Ihr Spiel relevantes Ereignis eintritt.

Wenn Sie ein Ereignis aktualisieren möchten, rufen Sie EventsClient.increment() mit dem Wert eventId und einer Ganzzahl incrementAmount auf, die größer oder gleich 0 ist.

  • Die eventId wird von den Google Play-Spieldiensten generiert, wenn Sie das Ereignis zum ersten Mal in der Google Play Console definieren. Sie dient zur eindeutigen Identifizierung dieses Ereignisses in Ihrem Spiel.
  • Mit der Eingabe incrementAmount können Sie den quantitativen Fortschritt des Spielers in Richtung eines spielspezifischen Ziels angeben. Wenn Sie beispielsweise das Ereignis 500 Glubschaugenmonster besiegen in Ihrem Spiel erfassen möchten, kann der incrementAmount-Wert die Anzahl der Monster sein, die der Spieler in einem einzelnen Kampf getötet hat.

Hier ein Beispiel dafür, wie Sie ein Ereignis mit einem Inkrementbetrag von 1 einreichen:

public void submitEvent(String eventId) {
  Games.getEventsClient(this, GoogleSignIn.getLastSignedInAccount(this))
      .increment(eventId, 1);
}

Ereignisse abrufen

Sie können alle Ereignisdaten, die auf den Google-Servern für Ihr Spiel gespeichert sind, mit dem Aufruf von EventsClient.load() abrufen. Übergeben Sie im Methodenaufruf einen booleschen Wert, um anzugeben, ob die lokal auf dem Gerät des Nutzers zwischengespeicherten Daten von Google Play-Spieldienste gelöscht werden sollen.

Wenn Sie Daten für bestimmte Ereignisse abrufen möchten, die Sie in der Google Play Console definiert haben, rufen Sie EventsClient.loadByIds() auf und übergeben Sie ein Array von Ereignis-IDs in den Eingabeparametern.

Das folgende Snippet zeigt, wie Sie die Google Play-Spieldienste nach der Liste aller Ereignisse für Ihr Spiel abfragen können:

public void loadEvents() {
  Games.getEventsClient(this, GoogleSignIn.getLastSignedInAccount(this))
      .load(true)
      .addOnCompleteListener(new OnCompleteListener<AnnotatedData<EventBuffer>>() {
        @Override
        public void onComplete(@NonNull Task<AnnotatedData<EventBuffer>> task) {
          if (task.isSuccessful()) {
            // Process all the events.
            for (Event event : task.getResult().get()) {
              Log.d(TAG, "loaded event " + event.getName());
            }
          } else {
            // Handle Error
            Exception exception = task.getException();
            int statusCode = CommonStatusCodes.DEVELOPER_ERROR;
            if (exception instanceof ApiException) {
              ApiException apiException = (ApiException) exception;
              statusCode = apiException.getStatusCode();
            }
            showError(statusCode);
          }
        }
      });
}