Ereignisse in Android-Spielen

In diesem Leitfaden erfahren Sie, wie Sie mithilfe der Ereignis-APIs von Google Play-Spieldiensten Daten zum Gameplay von Spielern für Analysen erfassen. Die APIs finden Sie unter com.google.android.gms.games.event und com.google.android.gms.games.

Hinweis

Sehen Sie sich gegebenenfalls die Konzepte für Ereignisspiele an.

Bevor Sie mit der Programmierung mit den Ereignis-APIs beginnen:

• Definieren Sie die Ereignisse für Ihr Spiel in der Google Play Console.
• Folgen Sie der Checkliste für die Anmeldung.

Events-Client abrufen

Damit Sie die Ereignis-APIs verwenden können, muss Ihr Spiel zuerst ein EventsClient-Objekt abrufen. Rufe dazu die Methode Games.getEventsClient() auf und übergebe die Aktivität und die GoogleSignInAccount für den aktuellen Spieler. Informationen zum Abrufen der Informationen zum Spielerkonto findest du unter Anmeldung in Android-Spielen.

Ereignisse einreichen

Sie können Code in Ihr Spiel einfügen, um Google Play Spieledienste 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 gleich oder größer als 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 dem Eingabewert incrementAmount können Sie den quantitativen Fortschritt des Spielers beim Erreichen eines spielspezifischen Ziels angeben. Wenn Sie beispielsweise das Ereignis „500 Augenmonster besiegen“ in Ihrem Spiel erfassen möchten, kann der Wert für incrementAmount die Anzahl der Monster sein, die der Spieler in einem einzigen Kampf getötet hat.

Hier ein Beispiel für das Senden eines Ereignisses mit einem Inkrementalabstand von 1:

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

Ereignisse abrufen

Sie können alle Ereignisdaten abrufen, die auf den Google-Servern für Ihr Spiel gespeichert sind, indem Sie EventsClient.load() aufrufen. Geben Sie beim Methodenaufruf einen booleschen Wert an, um anzugeben, ob die Google Play-Spieldienste die lokal im Cache des Nutzergeräts gespeicherten Daten löschen 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 geben Sie in den Eingabeparametern ein Array mit Ereignis-IDs an.

Im folgenden Snippet wird gezeigt, wie Sie die Google Play-Spieldienste um eine Liste aller Ereignisse für Ihr Spiel bitten:

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