Événements dans les jeux Android

Ce guide explique comment collecter les données de jeu à des fins d'analyse à l'aide des API Events fournies par les services de jeux Google Play. Ces API sont disponibles dans com.google.android.gms.games.event et com.google.android.gms.games.

Avant de commencer

Si ce n'est pas déjà fait, n'hésitez pas à revoir les concepts d'événement dans les jeux.

Avant de commencer à coder à l'aide des API Events :

• Définissez les événements de votre jeu dans la Google Play Console.

• Suivez les recommandations de la checklist de connexion.

Obtenir le client d'événements

Pour commencer à utiliser les API Events, votre jeu doit d'abord obtenir un objet EventsClient. Pour ce faire, il suffit d'appeler la méthode Games.getEventsClient() et de transmettre l'activité.

Remarque : La classe EventsClient utilise la classe Task des services Google Play pour renvoyer des résultats de manière asynchrone. Pour en savoir plus sur l'utilisation des tâches pour gérer les threads, consultez le guide du développeur de l'API Tasks.

Envoyer des événements

Vous pouvez ajouter du code dans votre jeu pour avertir les services de jeux Play chaque fois qu'un événement intéressant se produit.

Pour envoyer une notification d'événement, appelez EventsClient.increment() avec la valeur eventId et un entier incrementAmount supérieur ou égal à 0.

• L'identifiant eventId est généré par les services de jeux Play lorsque vous définissez l'événement dans la Google Play Console. Celui-ci permet d'identifier cet événement de manière unique dans votre jeu.
• Vous pouvez utiliser l'entrée incrementAmount pour spécifier la progression quantitative du joueur par rapport à un objectif spécifique au jeu. Par exemple, si l'événement à suivre par votre jeu est "Vaincre 500 monstres aux yeux d'insectes", la valeur incrementAmount peut correspondre au nombre de monstres que le joueur a éliminés en un seul combat.

Voici un exemple d'envoi d'un événement avec un incrément de 1 :

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

Récupérer des événements

Vous pouvez récupérer toutes les données d'événement stockées sur les serveurs de Google pour votre jeu en appelant EventsClient.load(). Dans l'appel de méthode, transmettez une valeur booléenne pour indiquer si les services de jeux Play doivent effacer les données mises en cache localement sur l'appareil de l'utilisateur.

Pour récupérer des données portant sur des événements spécifiques que vous avez définis dans la Google Play Console, appelez EventsClient.loadByIds() et transmettez un tableau d'ID d'événements dans les paramètres d'entrée.

L'extrait de code suivant montre comment interroger les services de jeux Play pour obtenir la liste de tous les événements de votre jeu :

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