Ereignisse für Android-Spiele

In diesem Leitfaden erfahren Sie, wie Sie mit den Ereignis-APIs der Google Play Games-Dienste Gameplay-Daten von Spielern für die Spielanalyse erheben. Die APIs befinden sich in den com.google.android.gms.games.event und com.google.android.gms.games Paketen.

Hinweis

Wir empfehlen Ihnen, sich vorab mit den Konzepten von Ereignissen in Spielen vertraut zu machen.

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

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

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

Ereignis-Client abrufen

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

Ereignisse einreichen

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

Wenn Sie eine Ereignisaktualisierung senden möchten, rufen Sie EventsClient.increment() mit dem eventId Wert und einem ganzzahligen Wert incrementAmount auf, der gleich oder größer als 0 ist.

• Die eventId wird von den Play Games-Diensten 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 Eingabe incrementAmount können Sie den quantitativen Fortschritt des Spielers beim Erreichen eines spielspezifischen Ziels angeben. Wenn das Ereignis, das Ihr Spiel erfassen möchte, „500 Käfermonster besiegen“ lautet, kann der incrementAmount Wert die Anzahl der Monster sein, die der Spieler in einem einzelnen Kampf getötet hat.

Hier sehen Sie ein Beispiel dafür, wie Sie ein Ereignis mit einem Erhöhungsbetrag 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, mit dem Aufruf von calling EventsClient.load() abrufen. Übergeben Sie im Methodenaufruf einen booleschen Wert, um anzugeben, ob die Play Games-Dienste die lokal im Cache gespeicherten Daten auf dem Gerät des Nutzers 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 übergeben Sie ein Array von Ereignis-IDs in den Eingabeparametern.

Das folgende Snippet zeigt, wie Sie die Play Games-Dienste nach der Liste aller Ereignisse für Ihr Spiel 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);
          }
        }
      });
}