Statistiques et classements
Tout d’abord, il est important de noter que toutes les statistiques définies pour un joueur dans un jeu dans PlayFab font partie d’un classement. Ainsi, définir vos statistiques définit également votre classement. Les statistiques ne sont pas nécessairement visibles par les joueurs, mais elles sont bien là. Vous pouvez les utiliser pour obtenir des listes de joueurs selon un score que vous définissez, que ce soit pour trouver les meilleurs scores, les plus bas, ceux centrés autour du joueur actuel ou ceux de la liste d’amis d’un utilisateur. De nombreuses statistiques dans les jeux sont destinées à être des valeurs à vie, ce qui signifie que les joueurs mettent continuellement à jour leurs scores, les anciens demeurant jusqu’à ce que chaque joueur batte son record personnel. Toutefois, pour certaines expériences de joueur, il est important de pouvoir « effacer » le classement de temps à autre. Cela peut servir à encourager un utilisateur à tenter d’être le joueur le mieux classé pendant une période donnée, ou simplement à retirer du classement les joueurs qui n’ont pas été actifs depuis un certain temps. Comme ce tutoriel l’expliquera, les statistiques dans PlayFab peuvent être configurées pour se réinitialiser selon un intervalle prédéterminé. Cela est utile non seulement pour les scénarios décrits ci-dessus, mais aussi pour les titres qui ont besoin d’un classement distinct des scores récents, qui peut servir pour des défis de jeu, par exemple lorsque vous voulez permettre à un joueur d’envoyer une invitation à quelqu’un d’un niveau d’habileté semblable. Définir une période de réinitialisation signifie que les joueurs renvoyés par un appel à GetLeaderboardAroundPlayer, par exemple, sont ceux qui ont joué récemment au jeu et qui ont des scores semblables à celui du joueur local. Il est également possible de réinitialiser une statistique manuellement. C’est un système pratique pour effacer les données de vos tests de prélancement ou de vos parties alpha/bêta. C’est aussi utile dans le pire des scénarios, lorsqu’un bogue introduit dans le code du jeu entraîne des scores incontrôlables. Dans chaque cas, vous devez pouvoir effacer complètement le classement, afin que les joueurs aient l’impression d’avoir une chance équitable d’y figurer.La réinitialisation des statistiques ne supprime pas ces valeurs, comme vous le verrez ci-dessous. Lors de la réinitialisation, les statistiques dans PlayFab sont versionnées : la nouvelle version devient la version de référence, tandis que les versions précédentes sont conservées pour une analyse ultérieure (et pour que vous puissiez récompenser les joueurs en fonction de leurs anciens scores).
Configurer des statistiques réinitialisables
Les périodes de réinitialisation des statistiques sont configurées à l’aide de l’ensemble d’API Admin ou de Game Manager. Elles peuvent ensuite être mises à jour et interrogées au moyen de Game Manager, de l’API Server et de l’API Client (toutefois, la publication de statistiques à partir du client exige que l’option allow client to post statistics soit activée dans l’onglet Settings->API Features du jeu dans Game Manager). Nous décrirons la méthode d’API à cette fin, bien que les paramètres définis ici soient les mêmes que ceux utilisés dans Game Manager. Pour configurer les statistiques, vous pouvez utiliser la méthode AdminCreatePlayerStatisticDefinition, puis la méthode UpdatePlayerStatisticDefinition pour apporter des modifications plus tard.
Dans les deux cas, il n’y a que deux paramètres :
StatisticName- L’identificateur de chaîne de la statistique du joueur.VersionChangeInterval- La période qui définit quand les statistiques doivent être réinitialisées automatiquement.
VersionChangeInterval est la clé de cette fonctionnalité; il peut être défini sur une base horaire, quotidienne, hebdomadaire ou mensuelle. Il peut également être défini à jamais, si vous décidez plus tard que vous ne voulez plus que la statistique se réinitialise régulièrement.
Dans l’exemple qui suit, l’appel à la méthode CreatePlayerStatisticDefinition configure la statistique Headshots avec une réinitialisation quotidienne, ce qui signifie que le classement de cette statistique dans le jeu sera réinitialisé chaque jour à 00:00 UTC.
PlayerStatisticDefinition, qui contient :
- L’identificateur de chaîne de la statistique (
StatisticName). - Le nombre de fois où la statistique a été réinitialisée (
CurrentVersion). - La période définie pour la réinitialisation de la statistique (
VersionChangeInterval).
- Never : Cesser de versionner la statistique en fonction du temps.
- Hour : Versionner la statistique au début de chaque heure (Hour) (XX:00 UTC).
- Day : Versionner la statistique à minuit (00:00 UTC) chaque jour (Day).
- Week : Versionner la statistique à minuit (00:00 UTC) chaque lundi.
- Month : Versionner la statistique à minuit (00:00 UTC) le premier jour de chaque mois.
Statistiques préexistantes
Il est possible d’interroger la définition de toutes les statistiques définies dans le jeu, qu’elles aient été configurées comme statistiques réinitialisables ou non. Il est important de le noter, puisque des statistiques peuvent être créées à l’aide de l’appel UpdatePlayerStatistics. Les statistiques qui n’ont pas été créées avec une période de réinitialisation (VersionChangeInterval) n’en ont pas au départ; une requête sur la configuration de la statistique renverrait donc ce paramètre défini à Never.
En reprenant l’exemple ci-dessus, si le titre avait aussi une statistique nommée FlagsCaptured créée à l’aide de UpdatePlayerStatistics (ou créée directement sur un joueur dans Game Manager), et que quelques semaines s’étaient écoulées, elle apparaîtrait comme dans l’appel ci-dessous.
Headshots a un intervalle de réinitialisation défini, et CurrentVersion indique que la statistique a été réinitialisée deux fois.
Pendant ce temps, FlagsCaptured n’a pas de VersionChangeInterval, ce qui explique aussi pourquoi CurrentVersion est à 0 (puisqu’elle n’a jamais été versionnée).
Les statistiques créées au moyen de UpdatePlayerStatistics (ou de Game Manager de PlayFab) peuvent quand même être définies avec une période de réinitialisation à l’aide de UpdatePlayerStatisticDefinition, comme décrit ci-dessus.
Une fois cela fait, elles seront réinitialisées selon cet intervalle exactement comme si elles avaient été définies à l’origine à l’aide de CreatePlayerStatisticDefinition.
Réinitialiser manuellement une statistique
Dans le cas où un bogue du jeu a permis de tricher sur une statistique, ou si vous devez simplement effectuer une réinitialisation pour supprimer les scores des parties préalables à la sortie, la statistique peut être réinitialisée de force dans Game Manager, ou au moyen d’un appel àIncrementPlayerStatisticVersion.
Cela réinitialise immédiatement les statistiques actuelles que vous spécifiez, efface le classement du jeu et offre une page blanche pour la déclaration de nouvelles valeurs.
Dans notre exemple, cet appel pourrait ressembler à celui illustré ci-dessous.
Headshots et renvoie des informations sur la version qui vient d’être activée.
PlayerStatisticVersion sont renvoyées; elles contiennent l’identificateur de la statistique (StatisticName), ainsi que son numéro de version, le moment où elle est devenue la version de référence (ActivationTime) et le ArchivalStatus (qui sera toujours NotScheduled pour la version actuelle).
Toutefois, pour une statistique qui a aussi un VersionChangeInterval, la réinitialisation manuelle ne modifiera pas l’heure de la prochaine réinitialisation planifiée. Si une statistique est planifiée pour se réinitialiser quotidiennement et qu’elle est réinitialisée manuellement à 23 h 30 UTC, elle sera quand même réinitialisée de nouveau à minuit UTC.
Moment de la réinitialisation
Comme mentionné, lorsque l’intervalle de réinitialisation survient, la statistique est versionnée, de sorte qu’une nouvelle version est immédiatement disponible, tandis que l’ancienne version de cette statistique est archivée pour une récupération ultérieure. Une fois l’intervalle de réinitialisation survenu (ou une réinitialisation manuelle effectuée) et la statistique versionnée, les écritures dans l’ancienne version sont acceptées pendant un maximum de dix minutes. Au-delà de ce délai, la statistique est verrouillée, ce qui empêche toute mise à jour ultérieure. Une fois expirées, les statistiques entrent dans le processus d’archivage, afin que le titre puisse les récupérer plus tard. Les étapes du processus d’archivage d’une statistique sont :- NotScheduled - L’archivage de la statistique n’a pas commencé (normalement seulement pour la version de statistique actuellement active).
- Scheduled - Le processus d’archivage a été planifié, mais n’est pas encore en cours.
- InProgress - La statistique est en cours de sauvegarde dans l’archive.
- Failed - Une défaillance inattendue s’est produite (dans ce cas, communiquez avec nos forums de soutien).
- Complete - Cette version de la statistique a été archivée.
GetPlayerStatisticVersions. Cela renvoie les informations de chaque version, comme dans l’exemple de réinitialisation manuelle précédent.
Autrement dit, cet appel devrait ressembler à celui présenté ci-dessous.
IncrementPlayerStatisticVersion, la réponse comprend aussi les horodatages d’expiration de chaque version (DeactivationTime) pour les versions antérieures à la version active, ainsi qu’une URL permettant de télécharger le fichier CSV contenant l’enregistrement complet de l’ancien classement, une fois le processus d’archivage terminé (ArchiveDownloadUrl).
Lecture et écriture dans les versions de statistiques
Enfin, du côté des API serveur et client, les appels sont très semblables à ceux que vous connaissez pour les appels originaux de statistiques d’utilisateur et de personnage de PlayFab. La différence est que maintenant, la version fait partie de la requête ou de la réponse. Lors de la récupération des statistiques, la valeur de la version actuelle de la statistique, ainsi que le numéro de version lui-même, sont renvoyés. Les exemples suivants montrent l’appel pour la statistiqueHeadshots, ainsi que les données renvoyées.
Requête serveur
Réponse du serveur
Requête client
Réponse du client
Update accepte une version facultative, afin de permettre au titre de contrôler quelle version est mise à jour, dans les cas où la version pourrait avoir été incrémentée pendant la partie.
Dans cet exemple, si le titre écrivait dans la version précédente tant que c’est encore possible, il écrirait dans la version 2, comme illustré ci-dessous.
Requête serveur
Réponse du serveur
Requête client
Réponse du client
Ressources
Par souci d’exhaustivité, cette section fournit la liste de toutes les énumérations, classes et méthodes d’API décrites ci-dessus, avec de brèves descriptions.Énumérations de base
-
Interval - période selon laquelle la statistique (classement) sera réinitialisée :
- Never
- Hour
- Day
- Week
- Month
-
StatisticVersionArchivalStatus - l’état du processus d’enregistrement des valeurs de statistiques des joueurs d’une version dans une archive téléchargeable :
- NotScheduled
- Scheduled
- InProgress
- Failed
- Complete
Classes de base et leurs membres
-
PlayerStatisticDefinition
- StatisticName (string) - Le nom unique de la statistique.
- CurrentVersion (string) - La version active actuelle de la statistique, incrémentée chaque fois que la statistique est réinitialisée.
- VersionChangeInterval (Interval) - L’intervalle auquel les valeurs de la statistique sont réinitialisées pour tous les joueurs.
-
PlayerStatisticVersion
- StatisticName (string) - Le nom de la statistique au moment où la version est devenue active.
- Version (string) - La version de la statistique (un nombre hexadécimal encodé sous forme de chaîne).
- ScheduledVersionChangeIntervalTime (DateTime) - Le moment auquel la version de la statistique devait devenir active, selon le ResetInterval configuré.
- CreatedTime (DateTime) - Le moment où la version de la statistique est devenue active.
- ArchivalStatus (StatisticVersionArchivalStatus) - L’état du processus d’enregistrement des valeurs de statistiques des joueurs de cette version dans une archive téléchargeable, s’il est configuré.
- ResetInterval (Interval) - L’intervalle de réinitialisation qui a déclenché l’activation de la version, s’il est configuré.
-
StatisticValue
- StatisticName (string) - Le nom unique de la statistique.
- Value (Int32) - La valeur de la statistique pour le joueur.
- Version (string) - Pour une valeur de statistique existante d’un joueur, la version de la statistique au moment où elle a été chargée.
-
StatisticUpdate
- StatisticName (string) - Le nom unique de la statistique.
- Version (string) - Pour les mises à jour d’une valeur de statistique d’un joueur, la version de la statistique à mettre à jour
- Value (Int32) - La valeur de la statistique pour le joueur.
Méthodes de l’API Admin
-
CreatePlayerStatisticDefinition
-
CreatePlayerStatisticDefinitionRequest
- Name (string) - longueur min. 1, longueur max. 128 - Le nom unique de la statistique.
- (VersionChangeInterval) (Interval) - L’intervalle auquel les valeurs de la statistique sont réinitialisées pour tous les joueurs (les réinitialisations commencent à la prochaine limite d’intervalle).
-
CreatePlayerStatisticDefinitionResult
- Statistic (PlayerStatisticDefinition) - La définition de la statistique créée.
-
CreatePlayerStatisticDefinitionRequest
-
UpdatePlayerStatisticDefinition
-
UpdatePlayerStatisticDefinitionRequest
- StatisticName (string) - Le nom unique de la statistique.
- VersionChangeInterval (Interval) - L’intervalle auquel les valeurs de la statistique sont réinitialisées pour tous les joueurs (les réinitialisations commencent à la prochaine limite d’intervalle).
-
UpdatePlayerStatisticDefinitionResult
- Statistic (PlayerStatisticDefinition) - La définition de la statistique créée.
-
UpdatePlayerStatisticDefinitionRequest
-
GetPlayerStatisticDefinitions
- GetPlayerStatisticDefinitionsRequest (aucun paramètre).
- GetPlayerStatisticDefinitionsResult
- Statistics (PlayerStatisticDefinition[]) - Le tableau des définitions pour la réinitialisation.
-
GetPlayerStatisticVersions
-
GetPlayerStatisticVersionsRequest
- StatisticName (string) - Le nom unique de la statistique.
-
GetPlayerStatisticVersionsResult
- StatisticVersions (PlayerStatisticVersion[]) - L’historique des changements de version de la statistique (toutes les versions).
-
GetPlayerStatisticVersionsRequest
-
IncrementPlayerStatisticVersion
-
IncrementPlayerStatisticVersionRequest
- StatisticName (string) - Le nom unique de la statistique.
-
IncrementPlayerStatisticVersionResult
- StatisticVersion (PlayerStatisticVersion) - La version de la statistique qui a expiré à la suite de cette opération (et son état d’archivage).
-
IncrementPlayerStatisticVersionRequest
Méthodes de l’API Client
-
GetPlayerStatistics
-
GetPlayerStatisticsRequest
- StatisticNames (string[]) - Tableau des statistiques à renvoyer, selon leurs noms uniques.
-
GetPlayerStatisticsResult
- Statistics (StatisticValue[]) - Tableau des données StatisticValue pour toutes les statistiques demandées.
-
GetPlayerStatisticsRequest
-
UpdatePlayerStatistics
-
UpdatePlayerStatisticsRequest
- Statistics (StatisticUpdate[]) - Les statistiques à mettre à jour, avec les valeurs fournies.
- UpdatePlayerStatisticsResult (aucun paramètre).
-
UpdatePlayerStatisticsRequest
Méthodes de l’API Server
-
GetPlayerStatistics
-
GetPlayerStatisticsRequest
- PlayFabId (string) - L’identifiant PlayFab du joueur dont les statistiques sont mises à jour.
- StatisticNames (string[]) - Tableau des statistiques à renvoyer, selon leurs noms uniques.
-
GetPlayerStatisticsResult
- Statistics (StatisticValue[]) - Tableau des données StatisticValue pour toutes les statistiques demandées.
-
GetPlayerStatisticsRequest
-
UpdatePlayerStatistics
-
UpdatePlayerStatisticsRequest
- PlayFabId (string) - L’identifiant PlayFab du joueur dont les statistiques sont mises à jour.
- Statistics (StatisticUpdate[]) - Les statistiques à mettre à jour, avec les valeurs fournies.
- UpdatePlayerStatisticsResult (aucun paramètre).
-
UpdatePlayerStatisticsRequest
