Ereignisse für Android-Spiele

In diesem Leitfaden erfahren Sie, wie Sie mithilfe der von Google Play-Spieldiensten bereitgestellten Event-APIs Gameplay-Daten von Spielern für die Spieleanalyse erfassen. Die APIs finden Sie in den Paketen com.google.android.gms.games.event und com.google.android.gms.games.

Hinweis

Falls Sie das noch nicht getan haben, sollten Sie sich die Spielkonzepte für Events ansehen.

Bevor Sie mit der Programmierung mit den Events APIs beginnen:

• Definieren Sie die Events für Ihr Spiel in der Google Play Console.

• Folgen Sie den Empfehlungen in der Checkliste für die Anmeldung.

Events-Client abrufen

Bevor Sie die Events 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 Ihrem Spiel Code hinzufügen, um die Play-Spieldienste zu benachrichtigen, wenn ein für Ihr Spiel relevantes Ereignis eintritt.

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

• Die eventId wird von den Play-Spieldiensten generiert, wenn Sie das Ereignis zum ersten Mal in der Google Play Console definieren. Sie wird verwendet, um dieses Ereignis in Ihrem Spiel eindeutig zu identifizieren.

• Mit der incrementAmount-Eingabe können Sie den quantitativen Fortschritt des Spielers beim Erreichen eines spielspezifischen Ziels angeben. Wenn das Ereignis, das in Ihrem Spiel erfasst werden soll, beispielsweise 500 glubschäugige Monster besiegen ist, kann der Wert incrementAmount 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) {
  PlayGames.getEventsClient(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 im Cache gespeicherten Daten auf dem Gerät des Nutzers von 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 Liste aller Ereignisse für Ihr Spiel über die Play-Spieldienste abfragen können:

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