Statistiques de jeu

Les statistiques de jeu sont des statistiques cumulées sur votre jeu que les joueurs peuvent consulter dans leur profil de joueur. Ces statistiques permettent aux joueurs de suivre leur progression globale, de revoir les moments forts et de se comparer à d'autres joueurs. Elles alimentent également les fonctionnalités Google Play telles que les quêtes, les défis sociaux et d'autres à venir.

Les statistiques de jeu doivent :

• ne nécessitent pas d'achat (par exemple, acheter des gemmes) : elles ne doivent pas être mises à jour à la suite d'un achat via une application.
• ne pas nécessiter de regarder des publicités (c'est-à-dire qu'elles ne doivent pas se mettre à jour après avoir regardé une publicité).
• Ne pas être une utilisation générique du jeu (par exemple, ouvrir le jeu ou utiliser les paramètres).
• Ne pas inclure de données utilisateur personnelles et sensibles, telles que définies dans le règlement Play, y compris les ID utilisateur, les mots de passe, la localisation précise ou les données de santé, ni aucun contenu offensant, vulgaire, sexuellement explicite, violent ou haineux.
• être disponible pour tous les utilisateurs (par exemple, il ne s'agit pas d'une action spécifique à une équipe ni d'une action disponible uniquement pour les utilisateurs d'un certain niveau ou limitée à des opérations en direct à durée limitée, etc.) ;

Procédure d'intégration

Envoyez des données à l'aide de l'API Statistiques de jeu en tant qu'événements de joueur pour les statistiques répétitives et un événement prédéfini progressUpdate pour la statistique de progression. Vous devrez également configurer la logique de calcul des statistiques qui apparaîtront sur le profil de joueur et les informations d'affichage correspondantes.

Les événements de joueur représentent des moments distincts dans le jeu, des boucles de jeu complètes ou des étapes de progression.

Un événement de joueur est défini et modélisé comme suit :

1. Un événement est représenté par une action spécifique effectuée par le joueur, comme terminer un match, une course ou une zone, déverrouiller un coffre ou enregistrer sa progression.
2. Chaque action entraîne certains résultats ou présente certaines caractéristiques qui la définissent. Elles sont modélisées en tant que propriétés d'événement qui fournissent du contexte sur l'événement et ses résultats spécifiques (par exemple, le type de match, les pièces collectées au cours de cette partie, le résultat du match ou le nombre de tirs à la tête).

L'intégration comprend les étapes suivantes :

• Déclarez le schéma de données brutes : définissez les événements de joueur à l'aide d'un import CSV dans la Play Console. Consultez Créer des événements.
• Intégrer l'API Statistiques de jeu : envoyez les données brutes des joueurs au format déclaré pour les événements de joueur et l'événement progressUpdate.
  • Envoyez tous les événements définis à l'aide de l'intégration côté client ou côté serveur. Pour en savoir plus, consultez les exemples pour les événements du lecteur et l'événement progressUpdate.
• Importez un fichier ZIP : fournissez trois fichiers CSV et tous les fichiers d'images d'icônes qui définissent cinq statistiques répétitives et un niveau de progression du joueur. Pour en savoir plus, consultez les exigences concernant les fichiers ZIP. Fournissez les informations suivantes :
  • Fichier CSV pour les statistiques répétitives :
    • Identifiant unique de la statistique.
    • Spécifiez le libellé d'événement à utiliser pour le calcul des statistiques. Vous ne pouvez pas utiliser le libellé d'événement progressUpdate ici.
      • Spécifiez le libellé de propriété à utiliser pour le calcul des statistiques. Il doit s'agir d'une propriété de l'événement spécifié.
      • Spécifiez le type d'agrégation (SUM, MAX, MIN ou COUNT) pour déterminer comment calculer la statistique sur le libellé de propriété sélectionné.
      • Spécifiez une condition de filtre facultative pour calculer la logique uniquement lorsque la condition est remplie. Définissez le libellé de propriété et d'événement, l'opérateur (=, <, <=, >= ou >) et la valeur du seuil.
    • Incluez un indicateur booléen pour indiquer si la statistique peut être utilisée pour les fonctionnalités compétitives.
    • Si la fonctionnalité peut être utilisée pour des fonctionnalités compétitives, les limites horaires minimales et maximales pour un joueur authentique. Cela nous permettra d'identifier les joueurs qui pourraient faire un usage abusif des fonctionnalités telles que les ligues et les défis sociaux.
    • Indiquez un nom à afficher unique pour la statistique que les joueurs verront.
    • Fournissez un texte unique décrivant la statistique. Cette description doit fournir des détails sur la façon dont le joueur l'obtient. Elle sera affichée aux joueurs dans l'interface utilisateur du profil de joueur.
    • Fournissez une icône unique représentant la statistique en saisissant le nom de fichier exact de l'icône dans le fichier CSV.
    • Indiquez, si vous le souhaitez, si une valeur croissante ou décroissante est bonne pour le joueur. Cette entrée sera utilisée pour célébrer les mouvements des joueurs.
    • Indiquez une unité de mesure facultative pour la statistique (par exemple, km, miles ou secondes).
  • Fichier CSV pour la statistique de progression du joueur :
    • Indiquez un nom à afficher unique pour la progression du joueur.
    • Fournissez une icône unique représentant la statistique.
    • Fournissez une description de la statistique de progression.
    • Indiquez, si vous le souhaitez, si une valeur croissante ou décroissante est bonne pour le joueur. Cette entrée ne sera utilisée pour célébrer les mouvements des joueurs que lorsque la propriété currentProgress est de type INT.
    • Indiquez une unité de mesure facultative pour la statistique (par exemple, km, miles ou secondes).
  • Fichier CSV pour la localisation : indiquez des noms à afficher localisés pour toutes les statistiques.
    • Ajoutez une ligne pour chaque localisation.
    • Utilisez la chaîne du nom à afficher de la statistique telle qu'elle a été ajoutée dans le fichier CSV précédent pour identifier de manière unique la statistique à laquelle la localisation est ajoutée.
    • Spécifiez la langue à partir d'une liste de codes de langue.
    • Ajoutez une localisation pour le nom à afficher dans la langue spécifiée.
    • Ajoutez une description localisée pour la statistique dans la langue spécifiée.

Planifier le schéma

Vous pouvez envoyer deux types de données à l'aide de l'API Statistiques de jeu : les événements de joueur et un événement prédéfini pour les statistiques de progression du joueur.

Les exemples suivants illustrent l'apparence des événements de joueur dans différents types de jeux :

Événements du lecteur

Les événements de joueurs sont définis par des moments distincts dans le jeu, des boucles de jeu complètes ou des étapes de progression.

• Définissez des événements comme des moments spécifiques du jeu, des boucles de jeu complètes ou des étapes de progression :
  • Achèvements de la boucle de jeu, comme un match ou une course terminés.
  • Étapes de progression, telles que la progression de l'exploration d'une zone enregistrée ou un niveau terminé.
  • Étant donné que les statistiques répétitives doivent réellement représenter des actions répétables par un joueur, les événements définis doivent être associés au gameplay de base.
• Ajoutez des propriétés pour fournir du contexte sur l'événement et ses résultats, comme le numéro du niveau, le type de match, le type d'arme, le nombre d'armes, les tirs à la tête, les pièces collectées, le résultat du match, le temps au tour ou le type de voiture.
• Envoyez les événements de la session de jeu dès qu'ils se produisent. Par exemple, envoyez un événement de fin de boucle de jeu immédiatement après la fin de la boucle.

progressUpdate Événement

Si votre jeu comporte un mécanisme de progression principal, utilisez cet événement pour envoyer la progression actuelle du joueur. L'événement comporte une propriété prédéfinie appelée "currentProgress" de type INT ou STRING. Vous devez envoyer la valeur actuelle de la progression du joueur dans le mécanisme de progression principal à l'aide de cette propriété. Si vous utilisez cet événement, la propriété prédéfinie "currentProgress" doit être présente et une statistique de progression doit être définie à l'aide de cette propriété.

Vous pouvez envoyer la valeur actuelle d'autres systèmes de progression de votre jeu, comme lifetime highest score ou current coin balance, en tant qu'autres propriétés de cet événement.

Étant donné que les joueurs peuvent comparer leurs profils en fonction de leur progression actuelle dans le jeu, il est important qu'il n'y ait aucun délai pour obtenir la valeur de progression actuelle après la première intégration. Pour représenter la progression actuelle de manière précise aux joueurs, vous devez envoyer l'événement progressUpdate au début de chaque session de jeu, ainsi qu'à chaque mise à jour de la progression actuelle.

Configurer vos statistiques

Vous devrez configurer vos statistiques répétitives et de progression en définissant la logique de calcul et les informations à afficher pour chaque statistique. Vous trouverez ci-dessous des exemples de statistiques répétitives pour différents genres de jeux. Les statistiques répétitives sont généralement des statistiques qui sont mises à jour de manière répétée pour n'importe quel joueur au cours de quelques sessions de jeu (3 à 4) et qui sont associées à la boucle de jeu principale.

Détails de l'intégration

Les points de terminaison de l'API et le SDK sont disponibles pour recueillir des commentaires anticipés. Ils seront en disponibilité générale (DG) à partir d'août 2026. Voir chronologie

Cette section explique comment créer des événements et les envoyer dans les intégrations côté client et côté serveur.

Quand envoyer des données

Les événements de joueur représentent les actions dans le jeu liées à la fin des boucles de jeu ou à des moments spécifiques dans le jeu. Envoyez ces événements dès qu'ils se produisent. Par exemple, envoyez l'événement de fin de boucle de jeu dès que la boucle est terminée.

progressUpdate Événement représente le niveau de progression actuel d'un joueur. Les données de statistiques de progression doivent être envoyées à l'aide de cet événement dans les situations suivantes :

1. Chaque fois que la progression actuelle est mise à jour, envoie immédiatement la dernière valeur.
2. Chaque fois qu'un joueur lance le jeu, afin de s'assurer que cette statistique est toujours présente pour un joueur.

Moyens d'intégration

Il existe deux méthodes d'intégration : côté client et de serveur à serveur.

Intégration de serveur à serveur

Un point de terminaison d'API publique vous permet d'envoyer des événements dans le corps de la requête à l'aide des configurations suivantes :

Paramètres de chemin d'accès

Autorisation et authentification

Les appels d'API de serveur à serveur suivent les consignes standards d'accès côté serveur aux services de jeux Play à l'aide d'OAuth 2.0. Les requêtes doivent inclure un jeton de support autorisé avec le champ d'application https://www.googleapis.com/auth/games.

Événements : corps de la requête

L'API de backend est soumise à des limites strictes de validation structurelle :

• Taille du lot : 30 événements maximum par BatchRecordEventsRequest.
• Nombre de propriétés : 25 propriétés personnalisées maximum par PlayerGameEvent.
• Limites de longueur : nom de l'événement (100 caractères maximum), clés de propriété (100 caractères maximum) et valeurs de chaîne de propriété (1 024 caractères maximum).
• ID de l'événement : doit être une chaîne UUID de 36 caractères valide.
• Nouvelle tentative et mise en cache : évitez de mettre en cache ou d'accumuler un nombre excessif d'événements en local en cas d'échec de l'API, car les nouvelles tentatives par lot dépassant 30 événements seront refusées. Effectuez toujours des nouvelles tentatives par blocs pour respecter la limite de taille de lot.

BatchRecordEventsRequest

Voir BatchRecordEventsRequest.

{
  "packageName": string,
  "requestTime": string,
  "events": [
    {
      object (PlayerGameEvent)
    }
  ]
}

PlayerGameEvent

{
  "eventId": string,
  "eventName": string,
  "eventProperties": {
    // keys (e.g., "matchId", "score")
    "": {
       object (PropertyValue)
    }
  },
  "eventTime": string // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z").
}

PropertyValue

// ONE of the following fields will be present:
{
// 64-bit integer formatted as a string to prevent data loss
"intValue": "string",
// Double-precision floating point number.
"doubleValue": number,
// Standard UTF-8 text string.
"stringValue": "string",
// Boolean value (true or false).
"boolValue": boolean,
// Duration in seconds suffixed with 's' (e.g., "240s" or "3.5s").
"durationValue": "string"
}

Événement progressUpdate : corps de la requête

BatchRecordEventsRequest

{
  "packageName": string,
  "requestTime": string,
  "events": [
    {
      object (PlayerGameEvent)
    }
  ]
}

PlayerGameEvent – progressUpdate

{
  "eventId": string,
  "eventName": "progressUpdate",
  "eventProperties": {
    "": {
       object (PropertyValue)
// Must have at least one property "currentProgress"  of  type  INT  or  STRING
    }
  },
  "eventTime": string // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z")
}

Corps de la réponse

En cas de réussite, renvoie un état HTTP 200 OK avec un objet JSON vide.

Exemple de corps de la requête

Événement : PlayerGameEvent

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-05-09T00:44:44Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID for deduplication and idempotency
      "eventName": "matchCompleted",
      "eventTime": "2026-05-09T01:44:44Z", // RFC 3339 formatted timestamp string (e.g., "2026-05-09T01:44:44Z").
      "eventProperties": {
        "matchId": {
          "stringValue": "Match_A"
        },
        "gameMode": {
          "stringValue": "Battle_B"
        },
        "locationId": {
          "stringValue": "Location_XYZ"
        },
        "playerElimination": {
          "intValue": 2
        },
        "isWinner": {
          "boolValue": true
        }
      }
    }
  ]
}

Événement progressUpdate

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-05-09T00:44:44Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID
      "eventName": "progressUpdate",
      "eventTime": "2026-05-09T01:44:44Z", // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z").
      "eventProperties": {
        "currentProgress": {
          "intValue": 52
        },
//Add more properties as per your requirement
      }
    }
  ]
}

Implémentations client

Pour en savoir plus sur l'implémentation client des statistiques de jeu pour votre plate-forme, consultez les ressources suivantes :

• Android
• Unity
• C++

Étapes