Eventi nei giochi Android

A seguito del ritiro dell'API Google Sign-in, rimuoveremo l'SDK di Google Play Services per i giochi v1 nel 2026. Dopo febbraio 2025, non potrai pubblicare su Google Play titoli appena integrati con l'SDK v1 per i giochi. Ti consigliamo di utilizzare invece l'SDK giochi v2.
Sebbene i titoli esistenti con le integrazioni precedenti della versione 1 dei giochi continuino a funzionare per un paio di anni, ti invitiamo a eseguire la migrazione alla versione 2 a partire da giugno 2025.
Questa guida è dedicata all'utilizzo dell'SDK Play Services v1. Per informazioni sulla versione più recente dell'SDK, consulta la documentazione della versione 2.

Questa guida mostra come raccogliere i dati di gameplay dei giocatori per le analisi dei giochi utilizzando le API di eventi fornite da Google Play Services per i giochi. 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, ti consigliamo di consultare i concetti dei giochi relativi agli eventi.

Prima di iniziare a scrivere codice utilizzando le API di eventi:

Ottenere il client di eventi

Per iniziare a utilizzare le API di eventi, il tuo gioco deve prima ottenere un oggetto EventsClient. Per farlo, chiama il metodo Games.getEventsClient() e passa l'attività e il GoogleSignInAccount per il player corrente. Per scoprire come recuperare i dati dell'account del giocatore, consulta Accedere a Giochi Android.

Inviare eventi

Puoi aggiungere codice al tuo gioco per notificare a Google Play Giochi Servizi 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 uguale o maggiore a 0.

  • eventId viene generato da Google Play Services per i giochi 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 con gli occhi sporgenti', il valore 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 gli eventi

Puoi recuperare tutti i dati sugli eventi memorizzati nei server di Google per il tuo gioco chiamando EventsClient.load(). Nella chiamata al metodo, passa un valore booleano per indicare se Google Play Services per i giochi deve 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 passa un array di ID evento nei parametri di input.

Il seguente snippet mostra come eseguire query su Google Play Services per i giochi per ottenere l'elenco di tutti gli eventi del 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);
          }
        }
      });
}