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, de se comparer à d'autres joueurs et d'alimenter les fonctionnalités Google Play telles que les quêtes, les défis sociaux et plus encore à l'avenir.
Procédure d'intégration
Envoyez des données à l'aide de l'API Game Stats sous forme d'événements de joueur flexibles pour les statistiques répétitives et d'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 du joueur et les informations les concernant.
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 :
- 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.
- 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 les consignes concernant les fichiers CSV.
- Intégration à l'API Game Stats : envoyez les données brutes des joueurs au format déclaré pour les événements de joueur flexibles 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 flexibles 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 flexibles et l'événement
- 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
progressUpdateici.- 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 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.
- 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 un ordre de séquence pour spécifier l'ordre dans lequel les statistiques s'affichent dans le profil de joueur.
- Indiquez, de manière facultative, si une valeur croissante ou décroissante est bénéfique 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, comme les kilomètres, les miles ou les 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é
currentProgressest 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.
- Fichier CSV pour les statistiques répétitives :
Consignes concernant les fichiers CSV pour les événements
Vous pouvez importer des événements à l'aide du fichier PlayerGameEvent.csv.
| Nom de fichier | Obligatoire ou facultatif |
| PlayerGameEvent.csv | Obligatoire |
Format de PlayerGameEvent.csv
Le fichier CSV contient l'événement déclaré et ses propriétés sous la forme de valeurs séparées par une virgule, dans l'ordre suivant :
Event Name,Property Name,Property Type
Si vous envoyez l'événement progressUpdate pour progressionStat, ajoutez une ligne pour cet événement. Cet événement doit contenir au moins une propriété currentProgress de type INT ou STRING, ainsi que toutes les autres propriétés que vous souhaitez envoyer.
Exemple de table
| Nom de l'événement | Nom de la propriété | Type de bien |
|---|---|---|
| matchCompleted | duration | DOUBLE |
| matchCompleted | Ennemis tués | INT |
| matchCompleted | isWinner | BOOLÉEN |
| matchCompleted | matchType | STRING (UTF-8) |
| itemCollected (Article collecté) | coinsAmount | INT |
| itemCollected (Article collecté) | weaponType | STRING (UTF-8) |
| progressUpdate | currentProgress | INT |
Consignes concernant les fichiers ZIP pour les statistiques
Vous pouvez importer des statistiques à la fois à l'aide d'un fichier ZIP. Reportez-vous au tableau pour connaître les noms de fichiers exacts à utiliser dans votre fichier ZIP :
| Nom de fichier | Obligatoire ou facultatif | Valeurs acceptées |
|---|---|---|
RepetitiveStatsConfig.csv
|
Obligatoire | Métadonnées pour de nombreux événements. |
ProgressionStatConfig.csv
|
Obligatoire | Événement déclaré et ses propriétés. |
StatLocalizations.csv
|
Facultatif | Fournit des traductions pour les noms et les descriptions des réussites. |
| Fichiers d'icônes | Obligatoire | Icônes au format PNG, JPEG ou JPG (512 x 512 pixels). |
Format de RepetitiveStatsConfig.csv
Le fichier CSV contient l'événement déclaré et ses propriétés sous la forme de valeurs séparées par une virgule, dans l'ordre suivant :
Stat ID, Event Name, Property Name, Aggregation, Stat Display Name, Stat Description, Filter Property, Filter Operator, Filter Value, Is Competitive, minLimit, maxLimit, Icon File Name, Sequence Number, Good value direction, unit
Si vous ne souhaitez pas utiliser la condition de filtre, laissez la cellule vide.
Exemple de table
| ID de la statistique | Nom de l'événement | Nom de la propriété | Agrégation | Nom à afficher de la statistique | Description de la statistique | Propriété de filtrage (facultatif) | Opérateur de filtre (facultatif) | Valeur du filtre (facultatif) | Est compétitif | minLimit | maxLimit | Nom de fichier de l'icône | Numéro de séquence | Direction de la valeur correcte | unité |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 | matchCompleted | duration | MAX | Survie de la correspondance la plus longue | Il s'agit du temps de survie d'un joueur dans un match. | isWinner | = | TRUE | TRUE | 0 | 50 | stat1.png | 1 | En baisse | secondes |
| 2 | matchCompleted | isWinner | COUNT | Matchs gagnés | Indique le nombre de matchs remportés par un joueur. | isWinner | = | TRUE | TRUE | 0 | 50 | stat3.png | 2 | En hausse | |
| 3 | matchCompleted | Ennemis tués | SUM | Éliminations en duel | Nombre d'éliminations lors de matchs en un contre un | matchType | = | "1-on-1" | FAUX | stat4.png | 4 | En hausse | |||
| 4 | itemCollected (Article collecté) | coinsAmount | SUM | Total d'or collecté | Un joueur collecte des pièces pendant un match | weaponType | = | "sword" | FAUX | stat2.png | 3 | En hausse |
Format de ProgressionStatConfig.csv
Le fichier CSV contient l'événement déclaré et ses propriétés sous la forme de valeurs séparées par une virgule, dans l'ordre suivant :
Stat ID, Stat Display Name, Stat Description, Icon File Name, Good value direction, unit
La statistique de progression sera la première à s'afficher dans le profil de joueur.
Exemple de table
| ID de la statistique | Nom à afficher de la statistique | Description de la statistique | Nom du fichier d'icône | Bon rapport qualité-prix |
| 5 | Niveau | Les joueurs accumulent de l'expérience en jouant des matchs et en passant au niveau supérieur. | Level.png | en augmentation |
Format de StatLocalizations.csv
Le fichier CSV contient l'événement déclaré et ses propriétés sous la forme de valeurs séparées par une virgule, dans l'ordre suivant :
Stat ID, Stat Display Name, Language Code, Localized Stat Name, Localized Stat Description
Exemple de table
| ID de la statistique | Nom à afficher de la statistique | Language Code | Nom de la statistique localisée (UTF-8) | Description localisée de la statistique (UTF-8) | 1 | Survie de la correspondance la plus longue | es | Survie plus longue dans les matchs | Cela indique la durée de survie d'une joueuse dans un match. | 1 | Survie de la correspondance la plus longue | fr | Survie du match le plus long | Cela indique la durée de survie d'un joueur dans n'importe quel match. | 4 | Total d'or collecté | es | Oro total recolectado | La jugadora recoge monedas mientras juega en un partido | 4 | Total d'or collecté | fr | Ou total collecté | Le joueur collecte des pièces en jouant un match |
Planifier le schéma
Vous pouvez envoyer deux types de données à l'aide de l'API Game Stats : des événements de joueur flexibles et un événement prédéfini pour les statistiques de progression du joueur. Les exemples suivants illustrent l'apparence des événements flexibles dans différents types de jeux.
Événements de lecteur flexible
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é.
- 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.
Exemples
| Type de jeu | Libellé d'événement | Moment dans le jeu / Événement de progression terminé / Boucle de jeu terminée | Résultat | Caractéristiques |
|---|---|---|---|---|
| Jeu de réflexion indé à progression linéaire | chapter_completed | Événement de progression terminé | ND | Numéro de chapitre, nom du chapitre, nombre d'essais, nombre d'écrans, nombre de mouvements, contenu du chapitre |
| screen_completed | Événement de progression terminé | Numéro du chapitre, nom du chapitre, nombre d'essais, nombre de mouvements, contenu du chapitre | ||
| Jeu de course infinie en 3D | run_completed | Achèvement de la boucle de jeu | Pièces collectées, score | Durée de la course, pièces collectées avec le jetpack, booster utilisé au début de la course, planches de surf utilisées, aimants utilisés, ressort utilisé, jetpack utilisé |
| RPG d'action en monde ouvert | areaExplorationProgress | Événement de progression terminé | Ennemis vaincus, potions collectées | Numéro de zone, nom de zone, pourcentage de progression |
| questCompleted | Fin de la boucle de jeu | ND | Nom de la quête | |
| weaponUnlocked | Moment dans le jeu | ND | Nom de l'arme, niveau de l'arme | |
| chestUnlocked | Moment dans le jeu | Minerai d'amélioration collecté | ||
| Casse-tête simple avec méta décorative | puzzleCompleted | Événement de progression / d'achèvement de la boucle de jeu | Pièces collectées, boosters collectés | Nombre de coups, cadeau de Butler utilisé ?, Type de niveau, numéro de niveau, boosters de couleur utilisés, dynamites utilisées |
| cardsCollected | Moment dans le jeu | Cartes à 1 étoile, cartes à 2 étoiles, cartes à 3 étoiles, nombre total de cartes | Numéro de l'album, nom de l'album | |
| Course arcade | raceCompleted | Fin de la boucle de jeu | Classement, NOS utilisé, temps de course | Type de course, classement, car_used |
| carUpgraded | Moment dans le jeu | Caractéristique de la voiture qui a été améliorée, ancien niveau / ancienne valeur, nouveau niveau / nouvelle valeur | Type de voiture, niveau actuel du garage | |
| Jeu de tir Battle Royale à la troisième personne | matchCompleted | Fin de la boucle de jeu | Éliminations, tirs à la tête, valeur d'honneur | Type de correspondance, durée de vie |
| Simulation de gestion d'e-sport | matchCompleted | Fin de la boucle de jeu | Résultat, buts marqués, buts | Nom de l'équipe adverse, nom de l'équipe qui joue |
| trainingCompleted | Moment dans le jeu | Exercices effectués : teamplay_form_attack, teamplay_form_defense, teamplay_form_possession, teamplay_form_condition |
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. Envoyez la valeur de la progression actuelle à l'aide de cette propriété, car il s'agit de la seule valeur qui s'affiche dans l'interface utilisateur des statistiques de jeu du profil du joueur.
É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 et chaque fois que la progression actuelle est mise à jour.
Exemples
| Type de jeu | Propriété currentProgress de l'événement `progressUpdate` |
|---|---|
| Jeu de réflexion à progression linéaire | Numéro de chapitre ou de niveau actuel |
| Jeu de course infinie en 3D | Meilleur score, solde de boosters actuel |
| Puzzle occasionnel | Numéro du niveau actuel, nombre de victoires au premier essai, nombre de zones terminées, nombre de collections terminées |
| Course arcade | Numéro du niveau actuel, solde de la devise |
| RPG d'action en monde ouvert | Rang actuel du personnage, numéro du niveau actuel |
| Tir à la troisième personne | Numéro de niveau actuel |
| Simulation d'e-sport | Numéro de niveau du responsable, numéro de niveau du club |
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 à partir de juillet 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 flexibles représentent des actions dans le jeu liées à la fin de la boucle de jeu ou à des moments spécifiques du 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 :
- Chaque fois que la progression actuelle est mise à jour, envoyez immédiatement la dernière valeur.
- 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
| Paramètre | Type de données | Description |
|---|---|---|
| playerId | Chaîne | ID PGS du joueur. |
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 flexibles : corps de la requête
BatchRecordEventsRequest
{ "packageName": string, "requestTime": string, "events": [ { object (PlayerGameEvent) } ] }
PlayerGameEvent
{ "eventId": string, "eventName": string, "eventProperties": { // keys (e.g., "matchId", "score") "" : { object (PropertyValue) } }, "eventTime": string }
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, // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z"). "timestampValue": "string", // 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 }
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 flexible : PlayerGameEvent
{ "packageName": "com.example.awesomegame",//Your package name "requestTime": "2026-01-01T18:00:00Z", "events": [ { "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID for deduplication //and idempotency "eventName": "matchCompleted", "eventTime": "2026-01-01T17:00:00Z", "eventProperties": { "matchId": { "stringValue": "Match_A" }, "gameMode": { "stringValue": "Battle_B" }, "locationId": { "stringValue": "Location_XYZ" }, "playerElimination": { "intValue": 2 }, "survivalTimeSeconds": { "durationValue": "240s" }, "isWinner": { "boolValue": true } } } ] }
Événement progressUpdate
{ "packageName": "com.example.awesomegame",//Your package name "requestTime": "2026-01-01T18:00:00Z", "events": [ { "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID "eventName": "progressUpdate", "eventTime": "2026-01-01T17:00:00Z", "eventProperties": { "currentProgress": { "intValue": 52 }, //Add more properties as per your requirement } } ] }
Intégration côté client
L'intégration côté client sera disponible à l'aide des SDK Unity, Java et C++.
L'intégration côté client pour PlayerGameEvent impliquerait que vous créiez l'objet d'événement en Java ou en C#, selon le SDK, au niveau des points de déclenchement et que vous l'envoyiez à l'aide des fonctions d'importation fournies par le SDK.
De même, pour l'événement progressUpdate, enregistrez la progression mise à jour à l'aide de la propriété currentProgress avec des propriétés supplémentaires définies, puis envoyez-les à l'aide des fonctions d'importation fournies par le SDK.
Événements
Voici les intégrations côté client pour PlayerGameEvent :
Créer un événement de jeu Flexible Player
Java
// Build the PlayerGameEvent
PlayerGameEvent event = new PlayerGameEvent.Builder("matchCompleted")
.addProperty("matchId", "Match_A")
.addProperty("gameMode", "Battle_B")
.addProperty("mapId", "Location_XYZ")
.addProperty("isWinner", true)
.addProperty("survivalTimeSeconds", "240s")
.addProperty("playerElimination", 2)
.build();
List events = new ArrayList<>();
// ... populate list ...
Unity
// Build the PlayerGameEvent
var playerEvent = new PlayerGameEvent.Builder("matchCompleted")
.AddProperty("matchId", "Match_A")
.AddProperty("gameMode", "Battle_B")
.AddProperty("mapId", "Location_XYZ")
.AddProperty("isWinner", true)
.AddProperty("survivalTimeSeconds", "240s")
.AddProperty("playerElimination", 2)
.Build();
var events = new List();
// ... populate list ...
C++
// Build the PlayerGameEvent
PgsPlayerGameEvent* player_event = PgsPlayerGameEvent_create("matchCompleted");
if (player_event != nullptr) {
PgsPlayerGameEvent_putString(player_event, "matchId", "Match_A");
PgsPlayerGameEvent_putString(player_event, "gameMode", "Battle_B");
PgsPlayerGameEvent_putString(player_event, "mapId", "Location_XYZ");
PgsPlayerGameEvent_putBoolean(player_event, "isWinner", true);
PgsPlayerGameEvent_putString(player_event, "survivalTimeSeconds", "240s");
PgsPlayerGameEvent_putLong(player_event, "playerElimination", 2);
}
Événement de jeu progressUpdate
Java
// Build the PlayerGameEvent
PlayerGameEvent event = new PlayerGameEvent.Builder("progressUpdate")
.addProperty("currentProgress", 52)
// Add other properties if needed
.build();
List events = new ArrayList<>();
// ... populate list ...
Unity
// Build the PlayerGameEvent
var progressEvent = new PlayerGameEvent.Builder("progressUpdate")
.AddProperty("currentProgress", 52)
// Add other properties if needed
.Build();
var events = new List();
// ... populate list ...
C++
PgsPlayerGameEvent* progress_event = PgsPlayerGameEvent_create("progressUpdate");
if (progress_event != nullptr) {
PgsPlayerGameEvent_putLong(progress_event, "currentProgress", 52);
}
Enregistrer un événement et l'importer
Java
// Buffers the event locally.
client.recordEvent(event);
// Buffers the events locally, (List version)
client.recordEvents(events);
// This submits the events to PGS
client.requestEventsUpload();
Unity
// Buffers the event locally.
PlayGamesPlatform.Instance.RecordEvent(playerEvent);
// Buffers the events locally, (List version)
PlayGamesPlatform.Instance.RecordEvents(events);
// This submits the events to PGS
PlayGamesPlatform.Instance.RequestEventsUpload();
C++
// Record the event
PgsGameStatsClient_recordEvent(client, player_event);
// This submits the events to PGS
PgsGameStatsClient_requestEventsUpload(client);
// Clean up handle to avoid leaks
PgsPlayerGameEvent_destroy(player_event);
// Clean up client handle when PGS operations are finished
PgsGameStatsClient_destroy(client);
Chronologie
| Date | Intégration de l'API Game Stats | Configuration des statistiques de jeu |
| Juin 2026 |
|
Non disponible |
| Juillet 2026 |
|
|
| Août 2026 | ND |
|
| Septembre 2026 | ND |
|