Eventi per i giochi Android

Questa guida illustra come raccogliere i dati di gameplay dei giocatori per l'analisi del gioco utilizzando le API Eventi fornite dai servizi per i giochi di Google Play. Le API sono disponibili in com.google.android.gms.games.event e com.google.android.gms.games.

Prima di iniziare

Se non l'hai ancora fatto, potrebbe esserti utile consultare i concetti relativi agli eventi.

Prima di iniziare a programmare utilizzando le API Events:

• Definisci gli eventi per il tuo gioco in Google Play Console.

• Segui i consigli relativi all'elenco di controllo per l'accesso.

Ottieni client eventi

Per iniziare a utilizzare le API Events, il gioco deve prima ottenere un oggetto EventsClient. Per farlo, chiama il metodo Games.getEventsClient() e trasmetti l'attività.

Nota: la classe EventsClient utilizza la classe Google Play Services Task per restituire i risultati in modo asincrono. Per scoprire di più sull'utilizzo delle attività per gestire il lavoro con conversazioni in thread, consulta la guida per gli sviluppatori dell'API Tasks.

Inviare eventi

Puoi aggiungere codice nel gioco per inviare una notifica ai servizi per i giochi di Play ogni volta che si verifica un evento di interesse nel gioco.

Per inviare un aggiornamento dell'evento, chiama EventsClient.increment() con il valore eventId e un numero intero incrementAmount uguale o maggiore di 0.

• L'eventId viene generato dai servizi per i giochi di Play quando definisci per la prima volta l'evento in Google Play Console e viene utilizzato per identificare in modo univoco questo evento nel tuo gioco.
• Puoi utilizzare l'input incrementAmount per specificare i progressi quantitativi del giocatore verso il completamento di un obiettivo specifico del gioco. Ad esempio, se l'evento che il tuo gioco vuole monitorare è "Sconfiggi 500 mostri dagli occhi infiammati", il valore incrementAmount può corrispondere al numero di mostri uccisi dal giocatore in una singola battaglia.

Ecco un esempio di come inviare un evento con un incremento di 1:

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

Recuperare eventi

Puoi recuperare tutti i dati sugli eventi memorizzati nei server di Google per il tuo gioco chiamando EventsClient.load(). Nella chiamata al metodo, inserisci un valore booleano per indicare se i servizi per i giochi di Play devono cancellare i dati memorizzati nella cache locale sul dispositivo dell'utente.

Per recuperare i dati relativi a eventi specifici che hai definito in Google Play Console, chiama EventsClient.loadByIds() e trasmetti un array di ID evento nei parametri di input.

Lo snippet seguente mostra come eseguire query sui servizi per i giochi di Play per visualizzare l'elenco di tutti gli eventi del gioco:

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