Ereignisse für Android-Spiele

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 in den Paketen com.google.android.gms.games.event und com.google.android.gms.games.

Hinweis

Falls Sie es noch nicht getan haben, sollten Sie sich die Game-Konzepte für Ereignisse ansehen.

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

Events-Client abrufen

Damit Sie die Ereignis-APIs verwenden können, muss Ihr Spiel zuerst ein EventsClient-Objekt abrufen. Rufen Sie dazu die Methode PlayGames.getEventsClient() auf und übergeben Sie die Aktivität.

Ereignisse einreichen

Sie können Code in Ihr Spiel einfügen, um die 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 0 entspricht oder größer ist.

  • Die eventId wird von den 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 incrementAmount-Eingabewert 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) {
  PlayGames.getEventsClient(this)
      .increment(eventId, 1);
}

Ereignisse abrufen

Sie können alle Ereignisdaten abrufen, die auf den Google-Servern für Ihr Spiel gespeichert sind. Rufen Sie dazu EventsClient.load() auf. Geben Sie beim Methodenaufruf einen booleschen Wert an, um anzugeben, ob die 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 von Ereignis-IDs an.

Das folgende Snippet zeigt, wie Sie die Play-Spieldienste um eine Liste aller Ereignisse für Ihr Spiel bitten:

public void loadEvents() {
  PlayGames.getEventsClient(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);
          }
        }
      });
}