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. Elles permettent aux joueurs de suivre leur progression globale, de revivre leurs temps forts et de se comparer à d'autres joueurs. Elles alimentent aussi les fonctionnalités de Google Play, comme les Quêtes, les Défis communautaires et bien d'autres à venir.

Les statistiques de jeu doivent :

  • Ne pas nécessiter d'achat (par exemple, l'achat de gemmes), c'est-à-dire qu'ils ne doivent pas être mis à jour à la suite d'un achat via l'application.
  • Ne pas nécessiter le visionnage d'annonces, c'est-à-dire qu'ils ne doivent pas être mis à jour après le visionnage d'une annonce.
  • Ne pas être une utilisation générique du jeu (par exemple, ouvrir le jeu, utiliser les paramètres).
  • Ne pas inclure de données utilisateur personnelles et sensibles, telles que définies par le règlement Play, y compris les ID utilisateur, les mots de passe, la position exacte ou les données de santé, ni tout contenu choquant, vulgaire, sexuellement explicite, violent ou incitant à la haine.
  • Être disponible pour tous les utilisateurs (par exemple, il ne doit pas s'agir d'une action spécifique à une équipe, ni d'une action disponible uniquement pour les utilisateurs d'un certain niveau ou limitée à des événements LiveOps à durée limitée, etc.)

L'image montre les statistiques de jeu dans le profil de joueur de l'onglet Vous. Cette interface utilisateur (UI) de l'onglet Vous n'est disponible qu'à des fins de test. L'UI des statistiques de jeu sera disponible en septembre 2026.

Statistiques de jeu dans l'onglet "Vous"
Statistiques de jeu avec les temps forts dans l'onglet "Vous".

Type d'agrégation

Le type d'agrégation indique à Google Play comment calculer une statistique à partir des valeurs par événement que vous envoyez :

  • SUM : à utiliser pour les statistiques cumulées (par exemple, le nombre total de pièces collectées ou le total des dégâts infligés). Le jeu doit envoyer le montant exact gagné lors de chaque instance d'événement.
  • COUNT : à utiliser pour les statistiques représentant le nombre d'occurrences d'un événement (par exemple, les parties jouées ou gagnées). Le jeu doit envoyer les instances d'occurrence d'événement distinctes.
  • MAX : à utiliser uniquement pour les records ponctuels (par exemple, le meilleur score d'une seule partie, la plus longue série de combos ou les dégâts les plus élevés d'un seul match). N'utilisez pas MAX comme solution de contournement pour afficher les totaux cumulés à partir de valeurs cumulées précalculées.

Exigence d'implémentation critique pour les statistiques répétitives

  • Envoyer des valeurs par événement : pour chaque événement, n'envoyez que ce qui s'est produit lors de cet événement, par exemple les pièces collectées lors d'une seule partie. Ensuite, définissez un type d'agrégation, tel que SUM ou COUNT, dans votre configuration de statistiques. Cela permet de s'assurer que les statistiques répétitives sont réutilisables dans les mécanismes d'engagement et permet à Google Play de créer les expériences de jeu appropriées.
  • N'envoyez pas de totaux cumulés : par exemple, ne suivez pas le nombre total de pièces qu'un joueur a collectées sur votre client ou serveur de jeu, et n'envoyez pas ce total avec l'agrégation MAX. Ces statistiques continueront d'être affichées dans l'interface utilisateur du profil de joueur, mais Google Play ne pourra pas les utiliser pour proposer des fonctionnalités gratifiantes telles que les ligues, les quêtes et les sprints afin d'améliorer l'expérience des joueurs et de générer un impact pour votre jeu.

Pour obtenir des instructions et des exemples de modélisation d'événements, consultez Événements de joueur et Configurer vos statistiques.

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 leurs informations d'affichage.

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

Un événement de lecteur 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 une partie, terminer une course, déverrouiller un coffre ou enregistrer sa progression dans une zone.
  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 un contexte sur l'événement et ses résultats spécifiques (par exemple, le type de match, les pièces collectées pendant 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 des données brutes : définissez les événements des joueurs en important un fichier CSV dans la Play Console. Consultez Créer des événements.
  • Intégrer l'API statistiques de jeu : envoyez des données brutes sur les joueurs au format déclaré pour les événements joueur et l'événement progressUpdate.
  • Importer un fichier ZIP : fournissez trois fichiers CSV et tous les fichiers d'image d'icône 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. Incluez 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 l'étiquette de la 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 l'étiquette de la propriété sélectionnée.
        • Spécifiez une condition de filtre facultative pour calculer la logique uniquement lorsque la condition est remplie. Définissez le libellé de la propriété et de l'événement, l'opérateur (=, <, <=, >= ou >) et la valeur de 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, limites horaires minimale et maximale pour un joueur authentique. Cela nous permettra d'identifier les joueurs qui pourraient faire un usage abusif de fonctionnalités telles que les ligues et les défis sociaux.
      • Indiquez un nom à afficher unique pour la statistique que les joueurs voient.
      • Fournissez un texte unique décrivant la statistique. Cette description doit expliquer comment le joueur l'obtient. Elle sera présentée aux joueurs dans l'interface utilisateur du profil de joueur.
      • Fournissez une icône unique représentant la statistique en saisissant le nom exact du fichier d'icône dans le fichier CSV.
      • Indiquez si une valeur croissante ou décroissante est bénéfique pour le joueur (facultatif). 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 et secondes.
    • Fichier CSV pour la statistique de progression du joueur :
      • Indiquez un nom à afficher unique pour la progression du joueur, que les joueurs verront.
      • Fournissez une icône unique représentant la statistique.
      • Fournissez une description de la statistique de progression.
      • Indiquez si une valeur croissante ou décroissante est bénéfique pour le joueur (facultatif). 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 : fournissez 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 pour laquelle la localisation est ajoutée.
      • Spécifiez la langue à partir d'une liste de codes de langue.
      • Ajoutez la localisation du nom à afficher dans la langue spécifiée.
      • Ajoutez la localisation de la description de 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 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 joueur

Les événements de joueur sont définis par des moments distincts dans le jeu, des boucles de jeu terminées ou des étapes de progression.

  • Définissez des événements comme des moments spécifiques du jeu, des fins de boucle de jeu ou des étapes de progression :
    • Boucles de jeu terminées, comme une partie ou une course terminée.
    • Les é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 véritablement représenter des actions répétables par un joueur, les événements définis doivent être associés au gameplay principal.
  • Ajoutez des propriétés pour fournir des informations 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 / Fin d'un événement de progression / Fin d'une boucle de jeu Résultat Caractéristiques
Jeu de réflexion indé à progression linéaire chapter_completed Progression de l'événement ND Numéro du chapitre, nom du chapitre, nombre d'essais, nombre d'écrans, nombre de déplacements, contenu du chapitre
screen_completed Progression de l'événement Numéro du chapitre, nom du chapitre, nombre d'essais, nombre de déplacements, contenu du chapitre
Jeu de course infinie en 3D run_completed Fin 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, jumper utilisé, jetpack utilisé
RPG d'action en monde ouvert areaExplorationProgress Progression de l'événement Ennemis vaincus, potions collectées Numéro de la zone, nom de la 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 du jeu Minerai d'amélioration collecté
Puzzle grand public avec méta décorative puzzleCompleted Fin de la boucle de jeu / Fin de l'événement de progression Pièces collectées, boosters collectés Nombre de déplacements, Cadeau du majordome utilisé ?, Type de niveau, numéro du niveau, boosters de couleur utilisés, dynamites utilisées
cardsCollected Moment dans le jeu Cartes 1 étoile, cartes 2 étoiles, cartes 3 étoiles, total des cartes Numéro de l'album, nom de l'album
Courses en mode arcade raceCompleted Fin de la boucle de jeu Rank, NOS used, race_time Type de course, note, voiture utilisée
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 match, temps de survie
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 Drills done, teamplay_form_attack, teamplay_form_defense, teamplay_form_possession, teamplay_form_condition

progressUpdate événement

Si votre jeu dispose d'un mécanisme de progression principal, utilisez cet événement pour envoyer la progression actuelle du joueur. L'événement possède 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 pour 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 exacte des joueurs, vous devez envoyer l'événement progressUpdate au début de chaque session de jeu, ainsi que 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 du chapitre ou du niveau actuel
Jeu de course sans fin en 3D Meilleur score, solde actuel de boosters
Puzzle grand public Numéro du niveau actuel, nombre de victoires au premier essai, nombre de zones terminées, nombre de collections terminées
Courses en mode 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
Jeu de tir à la troisième personne Numéro du niveau actuel
Simulation d'e-sport Numéro de niveau de responsable, numéro de niveau de club

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 d'un très petit nombre de sessions de jeu (3 ou 4) et qui sont associées à la boucle de jeu principale.

Pour savoir quand utiliser SUM, COUNT ou MAX, consultez Choisir le bon type d'agrégation.

Nom du jeu Nom à afficher de la statistique de jeu Propriété de l'événement Logique de calcul [aggregation] Filtrer
Jeu de course sans fin en 3D Exécutions terminées Toute propriété de l'événement run_completed Nombre Toutes les valeurs [aucun filtre]
Pièces collectées Propriété coins_collected de l'événement run_completed Somme ND
Clés collectées Propriété keys_collected de l'événement run_completed Somme ND
Meilleur score de course Propriété "score" de l'événement run_completed Max ND
Courses avec beaucoup de pièces terminées Propriété coins_collected de l'événement run_completed Nombre Valeur > 5 000
Jeu de réflexion à progression linéaire Chapitres terminés Toute propriété de l'événement chapter_completed Nombre Toutes les valeurs [aucun filtre]
Écrans terminés Toute propriété de l'événement screen_completed Nombre Toutes les valeurs [aucun filtre]
Chapitres terminés du premier coup Propriété num_try de l'événement chapter_completed Nombre Num_try = 1
Écrans terminés du premier coup Propriété num_try de l'événement screen_completed Nombre Num_try = 1
RPG d'action en monde ouvert Quêtes terminées Toute propriété de l'événement quest_completed Nombre Toutes les valeurs [aucun filtre]
Zones explorées Propriété perc_progress de l'événement area_exploration_progress Nombre Valeur = 100
Épées débloquées Propriété weapon_type de l'événement weapon_unlocked Nombre Valeur = "sword"
Ennemis vaincus Propriété enemies_defeated de l'événement area_exploration_progress Somme ND
Potions de santé collectées Propriété enhancement_ores de l'événement chest_unlocked Somme ND
Puzzle grand public Niveaux terminés Toute propriété de l'événement level_completed Nombre Toutes les valeurs [aucun filtre]
Niveaux terminés du premier coup Propriété num_try de l'événement level_completed Nombre Valeur = 1
Dynamiseurs de couleurs utilisés Propriété color_booster_used de l'événement level_completed Somme N/A
Boosters de bombe utilisés Propriété Bomb_booster_used de l'événement level_completed Somme N/A
Cartes collectées Propriété total_cards de l'événement cards_collected Somme N/A
Courses en mode arcade Victoires Propriété "rank" de l'événement "race_completed" Nombre Valeur = 1
Course la plus rapide Propriété race_time de l'événement race_completed Min N/A
NOS utilisé Propriété NOS_used de l'événement race_completed Somme N/A
Courses terminées avec une Mustang Propriété car_type de l'événement race_completed Nombre Valeur = "Mustang"
Améliorations de la voiture Toute propriété de l'événement car_upgraded Nombre Toutes les valeurs [aucun filtre]
Jeu de tir Battle Royale à la troisième personne Matchs gagnés Toute propriété de l'événement match_completed Nombre Match_result = TRUE
Nombre total d'éliminations Propriété "eliminations" de l'événement "match_completed" Somme N/A
Temps de survie le plus élevé Propriété survival_time de l'événement match_completed Max N/A
Total des tirs à la tête Propriété "headshots" de l'événement "match_completed" Somme N/A
Valeur totale de la compétence Propriété skill_value de l'événement match_completed Somme N/A
Simulation de gestion d'e-sport Matchs gagnés Propriété "result" de l'événement "match_completed" Nombre Résultat = "Gagné"
Total des buts marqués Propriété goals_scored de l'événement match_completed Somme N/A
Matchs difficiles gagnés Propriété "result" de l'événement hard_match_completed Nombre Résultat = "Gagné"
Victoire avec la plus grande différence de buts Propriété goal_difference de l'événement match_completed Max Résultat = "Gagné"
Nombre total d'exercices d'entraînement Propriété drills_done de l'événement training_completed Somme ND
Nombre total d'entraînements terminés Toute propriété de l'événement training_completed Nombre N/A

Détails de l'intégration

Cette section explique comment créer des événements et les envoyer dans des 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 d'une 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 se termine.

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

  1. Chaque fois qu'il y a une mise à jour de la progression actuelle, envoyez 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 types d'intégration : client et serveur à serveur.

Intégration de serveur à serveur

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

Requête HTTP

POST https://games.googleapis.com/games/v1/players/{playerId}/gameStats: batchRecordEvents

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 : corps de la requête

L'API de backend présente des limites strictes de validation structurelle :

  • Taille de lot : 30 événements maximum par BatchRecordEventsRequest.
  • Nombre de propriétés : 25 propriétés personnalisées au 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 d'événement : doit être une chaîne UUID valide de 36 caractères.
  • Nouvelle tentative et mise en cache : évitez de mettre en cache ou d'accumuler un nombre excessif d'événements localement en cas d'échec de l'API, car les nouvelles tentatives par lot dépassant 30 événements seront rejetées. Divisez toujours les nouvelles tentatives en fragments 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

Si l'opération réussit, renvoie un état HTTP 200 OK avec un objet JSON vide.

Exemple de corps de 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 du client de statistiques de jeu pour votre plate-forme, consultez les ressources suivantes :

Étapes

Date Intégration de l'API Statistiques de jeu Configuration des statistiques de jeu
Septembre 2026 ND Les joueurs commencent à voir les statistiques de jeu sur leur profil de joueur.