Ereignisse in Android-Spielen

Nach der Einstellung der Google-Anmeldung-API wird das games v1 SDK im Jahr 2026 entfernt. Ab Februar 2025 kannst du bei Google Play keine Titel mehr veröffentlichen, die neu in Games SDK V1 integriert wurden. Wir empfehlen, stattdessen das Games SDK V2 zu verwenden.
Bestehende Titel mit den vorherigen Games v1-Integrationen funktionieren zwar noch einige Jahre, aber wir empfehlen Ihnen, ab Juni 2025 zu Version 2 zu migrieren.
Dieser Leitfaden bezieht sich auf die Verwendung des Play-Spieldienste 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 Event-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 für Ereignisse vertraut zu machen, sofern Sie dies nicht schon getan haben.

Bevor Sie mit der Programmierung mit den Ereignis-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 Ihrem Spiel Code hinzufü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 das Ereignis, das in Ihrem Spiel erfasst werden soll, beispielsweise 500 Glubschaugenmonster besiegen ist, 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, abrufen, indem Sie EventsClient.load() aufrufen. Ü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);
          }
        }
      });
}