Eventi nei giochi Android

A seguito del ritiro dell'API Google Sign-In, rimuoveremo l'SDK v1 per i giochi nel 2026. Dopo febbraio 2025, non potrai pubblicare su Google Play titoli che sono stati integrati di recente con l'SDK v1 per i giochi. Ti consigliamo di utilizzare l'SDK v2 per i giochi.
Anche se i titoli esistenti integrati in precedenza con l'SDK v1 per i giochi continueranno a funzionare per un paio di anni, ti consigliamo di eseguire la migrazione all'SDK v2 a partire da giugno 2025.
Questa guida riguarda l'utilizzo dell'SDK Play Games Services v1. Per informazioni sull'ultima versione dell'SDK, consulta la documentazione della versione 2.

Questa guida mostra come raccogliere i dati di gioco dei giocatori per l'analisi del gioco utilizzando le API Events for Analytics fornite da Google Play Games Services. Le API sono disponibili nei pacchetti com.google.android.gms.games.event e com.google.android.gms.games.

Prima di iniziare

Se non l'hai ancora fatto, potrebbe esserti utile rivedere i concetti di gioco degli eventi.

Prima di iniziare a scrivere codice utilizzando le API Events:

Scaricare il client di Events

Per iniziare a utilizzare le API Events, il gioco deve prima ottenere un oggetto EventsClient. Per farlo, chiama il metodo Games.getEventsClient() e passa l'attività e il parametro GoogleSignInAccount per il giocatore corrente. Per scoprire come recuperare le informazioni dell'account del giocatore, consulta la sezione Accesso nei giochi per Android.

Inviare eventi

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

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

  • L'eventId viene generato dai servizi per i giochi di Google 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 l'avanzamento quantitativo 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 con gli occhi a palla", il valore di incrementAmount può essere il numero di mostri uccisi dal giocatore in una singola battaglia.

Ecco un esempio di come inviare un evento con un importo di incremento pari a 1:

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

Recuperare eventi

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

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

Il seguente snippet mostra come puoi eseguire query sui servizi per i giochi di Google Play per ottenere l'elenco di tutti gli eventi per il tuo gioco:

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