Utilisation des statistiques et classements réinitialisables

Ce tutoriel fournit une présentation complète de la configuration et de la gestion des statistiques avec gestion des versions, ce qui permet la réinitialisation des statistiques et, par extension, des classements. Nous nous concentrerons sur l’utilisation des méthodes de l’API Admin, avec des informations supplémentaires sur l’utilisation des méthodes des API client et Server pour interroger les données, aussi bien pour la version actuelle que pour les anciennes. Notre objectif est de vous fournir une présentation technique du fonctionnement des statistiques réinitialisables dans PlayFab, ainsi que de toutes les façons dont elles peuvent être utilisées dans vos jeux.

Statistiques et classements

Tout d’abord, il est important de noter que toutes les statistiques définies pour un joueur dans un jeu sur PlayFab font partie d’un classement. Définir vos statistiques revient donc également à définir votre classement. Les statistiques ne sont pas nécessairement visibles par les joueurs, mais elles existent. 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 moins bons, ceux centrés autour du joueur actuel ou ceux de la liste d’amis d’un utilisateur. De nombreuses statistiques dans les jeux sont conçues comme des valeurs à vie : les joueurs mettent continuellement à jour leurs scores, et les anciens subsistent jusqu’à ce que chaque joueur batte son record personnel. Cependant, pour certaines expériences de joueur, il est important de pouvoir « effacer » le classement de temps en temps. 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 inactifs depuis un certain temps. Comme ce tutoriel l’expliquera, les statistiques dans PlayFab peuvent être configurées pour se réinitialiser à 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, utilisable par exemple pour des défis de jeu, lorsque vous souhaitez permettre à un joueur d’inviter quelqu’un d’un niveau de compétence similaire. 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 et dont les scores sont similaires à 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 issues de vos tests de prélancement ou de vos phases alpha/bêta. C’est également utile dans le pire des scénarios, lorsqu’un bogue introduit dans le code du jeu a entraîné des scores incontrôlés. Dans chaque cas, vous devez pouvoir remettre à zéro le classement, afin que les joueurs aient le sentiment 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 d’une réinitialisation, les statistiques dans PlayFab sont versionnées : la nouvelle version fait autorité, tandis que les versions précédentes sont conservées pour une analyse ultérieure (et pour vous permettre de récompenser les joueurs en fonction de leurs anciens scores).

Configuration des statistiques réinitialisables

Les périodes de réinitialisation des statistiques sont configurées à l’aide de l’API Admin ou de Game Manager. Elles peuvent ensuite être mises à jour et interrogées via Game Manager, l’API Server et l’API client (bien que la publication de statistiques depuis le client nécessite 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 correspondante, mais les paramètres définis ici sont les mêmes que ceux utilisés dans Game Manager. Pour configurer les statistiques, vous pouvez utiliser la méthode Admin CreatePlayerStatisticDefinition, puis la méthode UpdatePlayerStatisticDefinition pour apporter des modifications ultérieurement. Dans les deux cas, il n’y a que deux paramètres :

StatisticName - Identificateur de type chaîne de la statistique de joueur.
VersionChangeInterval - Période définissant quand les statistiques doivent être réinitialisées automatiquement.

VersionChangeInterval est l’élément clé de cette fonctionnalité ; il peut être défini sur toutes les heures, tous les jours, toutes les semaines ou tous les mois. Il peut également être défini sur jamais, si vous décidez plus tard que vous ne souhaitez plus que la statistique soit réinitialisée 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.

public void CreatePlayerStatisticDefinition() {
    PlayFabAdminAPI.CreatePlayerStatisticDefinition(
        new CreatePlayerStatisticDefinitionRequest() {
            StatisticName = "Headshots",
            VersionChangeInterval = StatisticResetIntervalOption.Day
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

Voici la réponse à l’appel d’API précédent.

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "Statistic":
        {
            "StatisticName": "Headshots",
            "CurrentVersion": 0,
            "VersionChangeInterval": "Day"
        }
    }
}

Le code ci-dessous constitue un autre exemple.

public void UpdatePlayerStatisticDefinition() {
    PlayFabAdminAPI.UpdatePlayerStatisticDefinition(
        new UpdatePlayerStatisticDefinitionRequest() {
            StatisticName = "Headshots",
            VersionChangeInterval = StatisticResetIntervalOption.Week
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

Cet appel montre comment définir la période de réinitialisation de la statistique sur hebdomadaire, avec la réponse suivante.

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "Statistic":
        {
            "StatisticName": "Headshots",
            "CurrentVersion": 0,
            "VersionChangeInterval": "Week"
        }
    }
}

Dans chaque cas, le résultat est le PlayerStatisticDefinition, qui contient :

L’identificateur de type 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).

Les périodes de réinitialisation prennent effet dès leur définition. Dans ce cas, le deuxième appel signifie que la réinitialisation est désormais définie à 00:00 UTC le lundi matin (minuit dans la nuit du dimanche au lundi, selon le fuseau horaire UTC), quelle que soit la configuration antérieure à l’appel. Les autres intervalles de réinitialisation sont également définis en UTC ; avec Month, la réinitialisation a lieu à 00:00 UTC le premier jour de chaque mois. Voici la liste complète des périodes de réinitialisation :

Never : arrêter la gestion des versions de la statistique en fonction du temps.
Hour : versionner la statistique au début de chaque heure (XX:00 UTC).
Day : versionner la statistique à minuit (00:00 UTC) chaque jour.
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

La définition de toutes les statistiques définies dans le jeu peut être interrogée, qu’elles aient été configurées comme statistiques réinitialisables ou non. Il est important de le noter, car 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 renverra donc ce paramètre avec la valeur Never. En reprenant l’exemple ci-dessus, si le titre possédait également une statistique nommée FlagsCaptured créée à l’aide de UpdatePlayerStatistics (ou créée dans Game Manager directement sur un joueur), et que quelques semaines s’étaient écoulées, elle apparaîtrait comme dans l’appel ci-dessous.

public void GetPlayerStatisticDefinitions() {
    PlayFabAdminAPI.GetPlayerStatisticDefinitions(
        new GetPlayerStatisticDefinitionsRequest(),
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

Ce qui donnerait le résultat suivant.

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "Statistics": [
        {
            "StatisticName": "Headshots",
            "CurrentVersion": 2,
            "VersionChangeInterval": "Week"
        },
        {
            "StatisticName": "FlagsCaptured",
            "CurrentVersion": 0,
            "VersionChangeInterval": “Never”
        }]
    }
}

Dans ce cas, la statistique nommée Headshots possède un intervalle de réinitialisation défini, et CurrentVersion indique que la statistique a été réinitialisée deux fois. En revanche, FlagsCaptured n’a pas de VersionChangeInterval, ce qui explique aussi pourquoi CurrentVersion vaut 0 (puisqu’elle n’a jamais été versionnée). Les statistiques créées via UpdatePlayerStatistics (ou via PlayFab Game Manager) peuvent tout de même être dotées d’une période de réinitialisation à l’aide de UpdatePlayerStatisticDefinition, comme décrit ci-dessus. Une fois cela fait, elles seront réinitialisées à cet intervalle exactement comme si elles avaient été définies à l’origine avec CreatePlayerStatisticDefinition.

Réinitialisation manuelle d’une statistique

Dans le cas où un bogue du jeu a permis de tricher sur une statistique, ou si vous devez simplement supprimer les scores issus des sessions de jeu antérieures à la sortie, vous pouvez forcer la réinitialisation de la statistique dans Game Manager ou via un appel à IncrementPlayerStatisticVersion. Cela réinitialise immédiatement les statistiques actuelles que vous spécifiez, en vidant le classement du jeu et en offrant une page blanche pour les nouvelles valeurs à enregistrer. Dans notre exemple, cet appel pourrait ressembler à celui présenté ci-dessous.

public void IncrementPlayerStatisticVersion() {
    PlayFabAdminAPI.IncrementPlayerStatisticVersion(
        new IncrementPlayerStatisticVersionRequest() {
            StatisticName = "Headshots"
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

Cela incrémente une fois de plus la statistique Headshots et renvoie des informations sur la version qui vient d’être activée.

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "StatisticVersion":
        {
            "StatisticName": "Headshots",
            "Version": 3,
            "ActivationTime": "2016-02-03T08:02:29.864Z",
            "ArchivalStatus": "NotScheduled"
        }
    }
}

Dans ce cas, les informations PlayerStatisticVersion sont renvoyées ; elles contiennent l’identificateur de la statistique (StatisticName), ainsi que son numéro de version, l’heure à laquelle elle est devenue la version faisant autorité (ActivationTime) et le ArchivalStatus (qui sera toujours NotScheduled pour la version actuelle). Cependant, pour une statistique qui possède également un VersionChangeInterval, une réinitialisation manuelle ne modifiera pas l’heure de la prochaine réinitialisation planifiée. Si une statistique doit être réinitialisée quotidiennement et qu’elle est réinitialisée manuellement à 23 h 30 UTC, elle sera tout de même réinitialisée à nouveau à minuit UTC.

Quand la réinitialisation a lieu

Comme indiqué, lorsque l’intervalle de réinitialisation survient, la statistique est versionnée : 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 atteint (ou une réinitialisation manuelle effectuée) et la statistique versionnée, les écritures dans l’ancienne version sont acceptées pendant dix minutes au maximum. Passé 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 ultérieurement. Les étapes du processus d’archivage d’une statistique sont les suivantes :

NotScheduled - L’archivage de la statistique n’a pas commencé (normalement uniquement 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, contactez nos forums de support).
Complete - Cette version de la statistique a été archivée.

Toutes les versions passées et actuelles d’une statistique peuvent être interrogées à l’aide de GetPlayerStatisticVersions. Cette méthode 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.

public void GetPlayerStatisticVersions() {
    PlayFabAdminAPI.GetPlayerStatisticVersions(
        new GetPlayerStatisticVersionsRequest() {
            StatisticName = "Headshots"
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

Cela pourrait renvoyer les informations suivantes pour notre titre d’exemple.

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "StatisticVersions": [
        {
            "StatisticName": "Headshots",
            "Version": 0,
            "ActivationTime": "2015-01-20T05:47:27.17Z",
            "DeactivationTime": "2016-01-25T00:00:00.000Z",
            "ArchivalStatus": "Complete",
            "ArchiveDownloadUrl": {{URL}}
        },
        {
            "StatisticName": "Headshots",
            "Version": 1,
            "ActivationTime": "2016-01-25T00:00:00.000Z",
            "DeactivationTime": "2016-02-01T00:00:00.000Z",
            "ArchivalStatus": "Complete",
            "ArchiveDownloadUrl": {{URL}}
        },
        {
            "StatisticName": "Headshots",
            "Version": 2,
            "ActivationTime": "2016-02-01T00:00:00.000Z",
            "DeactivationTime": "2016-02-03T08:02:29.864Z",
            "ArchivalStatus": "InProgress"
        },
        {
            "StatisticName": "Headshots",
            "Version": 3,
            "ActivationTime": "2016-02-03T08:02:29.864Z",
            "ArchivalStatus": "NotScheduled"
        }]
    }
}

En plus des valeurs renvoyées par IncrementPlayerStatisticVersion, la réponse inclut également les horodatages d’expiration de chaque version (DeactivationTime) pour les versions antérieures à la version active actuelle, 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 des versions de statistiques

Enfin, côté API Server et client, les appels sont très similaires à ceux que vous connaissez pour les statistiques d’utilisateur et de personnage PlayFab d’origine. La différence est que la version fait désormais partie de la requête ou de la réponse. Lors de la récupération des statistiques, la valeur de la version de statistique actuelle, ainsi que le numéro de version lui-même, sont renvoyés. Les exemples suivants montrent l’appel pour la statistique Headshots, ainsi que les données renvoyées.

Requête serveur

public void GetPlayerStatistics() {
    PlayFabServerAPI.GetPlayerStatistics(
        new GetPlayerStatisticsRequest() {
            PlayFabId= "_PlayFabId_",
            StatisticNames = new List<string>() { "Headshots" }
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

Réponse du serveur

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "PlayFabId": {{PlayFabId}},
        "Statistics": [
        {
            "StatisticName": "Headshots",
            "Value": 10,
            "Version": "3"
        }]
    }
}

Requête client

public void GetPlayerStatistics() {
    PlayFabClientAPI.GetPlayerStatistics(
        new GetPlayerStatisticsRequest() {
            StatisticNames = new List<string>() { "Headshots" }
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

Réponse du client

{
    "code": 200,
    "status": "OK",
    "data": {
        "Statistics": [
        {
            "StatisticName": "Headshots",
            "Value": 10,
            "Version": "3"
        }]
    }
}

Par ailleurs, l’appel Update accepte une version facultative, afin de permettre au titre de contrôler quelle version est mise à jour, dans les cas où la version aurait été incrémentée pendant la partie.

Dans cet exemple, si le titre devait écrire 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

public void UpdatePlayerStatistics() {
    PlayFabServerAPI.UpdatePlayerStatistics(
        new UpdatePlayerStatisticsRequest() {
            PlayFabId= "_PlayFabId_",
            Statistics = new List<StatisticUpdate>() {
                new StatisticUpdate() {
                    StatisticName = "Headshots",
                    Version = 2,
                    Value = 10
                }
            }
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

Réponse du serveur

{
    "code": 200,
    "status": "OK",
    "data": {}
}

Requête client

public void UpdatePlayerStatistics() {
    PlayFabClientAPI.UpdatePlayerStatistics(
        new UpdatePlayerStatisticsRequest() {
            Statistics = new List<StatisticUpdate>() {
                new StatisticUpdate() {
                    StatisticName = "Headshots",
                    Version = 2,
                    Value = 10
                }
            }
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

Réponse du client

{
    "code": 200,
    "status": "OK",
    "data": {}
}

Mais n’oubliez pas : si la version expirée peut recevoir des écritures pendant 10 minutes au maximum, toute tentative d’écriture dans cette version au-delà de ce délai échouera, avec une réponse semblable à celle présentée ci-dessous.

{
    "code": 400,
    "status": "BadRequest",
    "error": "StatisticVersionClosedForWrites",
    "errorCode": 1197,
    "errorMessage": "The statistic version is not current and is no longer accepting updates"
}

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 à laquelle la statistique (classement) sera réinitialisée :
- Never
- Hour
- Day
- Week
- Month
StatisticVersionArchivalStatus - état du processus d’enregistrement des valeurs de statistiques de joueur d’une version dans une archive téléchargeable :
- NotScheduled
- Scheduled
- InProgress
- Failed
- Complete

Classes de base et leurs membres

PlayerStatisticDefinition
- StatisticName (string) - Nom unique de la statistique.
- CurrentVersion (string) - Version active actuelle de la statistique, incrémentée à chaque réinitialisation de la statistique.
- VersionChangeInterval (Interval) - Intervalle auquel les valeurs de la statistique sont réinitialisées pour tous les joueurs.
PlayerStatisticVersion
- StatisticName (string) - Nom de la statistique au moment où la version est devenue active.
- Version (string) - Version de la statistique (nombre hexadécimal encodé sous forme de chaîne).
- ScheduledVersionChangeIntervalTime (DateTime) - Heure à laquelle l’activation de la version de la statistique était planifiée, en fonction du ResetInterval configuré.
- CreatedTime (DateTime) - Heure à laquelle la version de la statistique est devenue active.
- ArchivalStatus (StatisticVersionArchivalStatus) - État du processus d’enregistrement des valeurs de statistiques de joueur de cette version dans une archive téléchargeable, si configuré.
- ResetInterval (Interval) - Intervalle de réinitialisation ayant déclenché l’activation de la version, si configuré.
StatisticValue
- StatisticName (string) - Nom unique de la statistique.
- Value (Int32) - Valeur de la statistique pour le joueur.
- Version (string) - Pour une valeur de statistique existante d’un joueur, version de la statistique au moment de son chargement.
StatisticUpdate
- StatisticName (string) - Nom unique de la statistique.
- Version (string) - Pour les mises à jour de la valeur de statistique d’un joueur, version de la statistique à mettre à jour
- Value (Int32) - Valeur de la statistique pour le joueur.

Méthodes de l’API Admin

CreatePlayerStatisticDefinition
- CreatePlayerStatisticDefinitionRequest
  - Name (string) - longueur min. 1, longueur max. 128 - Nom unique de la statistique.
  - (VersionChangeInterval) (Interval) - 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) - Définition de la statistique créée.
UpdatePlayerStatisticDefinition
- UpdatePlayerStatisticDefinitionRequest
  - StatisticName (string) - Nom unique de la statistique.
  - VersionChangeInterval (Interval) - 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) - Définition de la statistique créée.
GetPlayerStatisticDefinitions
- GetPlayerStatisticDefinitionsRequest (aucun paramètre).
- GetPlayerStatisticDefinitionsResult
  - Statistics (PlayerStatisticDefinition[]) - Tableau des définitions pour la réinitialisation.
GetPlayerStatisticVersions
- GetPlayerStatisticVersionsRequest
  - StatisticName (string) - Nom unique de la statistique.
- GetPlayerStatisticVersionsResult
  - StatisticVersions (PlayerStatisticVersion[]) - Historique des changements de version de la statistique (toutes les versions).
IncrementPlayerStatisticVersion
- IncrementPlayerStatisticVersionRequest
  - StatisticName (string) - Nom unique de la statistique.
- IncrementPlayerStatisticVersionResult
  - StatisticVersion (PlayerStatisticVersion) - Version de la statistique ayant expiré à la suite de cette opération (et son état d’archivage).

Méthodes de l’API client

GetPlayerStatistics
- GetPlayerStatisticsRequest
  - StatisticNames (string[]) - Tableau des statistiques à renvoyer, désignées par leurs noms uniques.
- GetPlayerStatisticsResult
  - Statistics (StatisticValue[]) - Tableau de données StatisticValue pour toutes les statistiques demandées.
UpdatePlayerStatistics
- UpdatePlayerStatisticsRequest
  - Statistics (StatisticUpdate[]) - Statistiques à mettre à jour, avec les valeurs fournies.
- UpdatePlayerStatisticsResult (aucun paramètre).

Méthodes de l’API Server

GetPlayerStatistics
- GetPlayerStatisticsRequest
  - PlayFabId (string) - Identifiant PlayFab du joueur dont les statistiques sont mises à jour.
  - StatisticNames (string[]) - Tableau des statistiques à renvoyer, désignées par leurs noms uniques.
- GetPlayerStatisticsResult
  - Statistics (StatisticValue[]) - Tableau de données StatisticValue pour toutes les statistiques demandées.
UpdatePlayerStatistics
- UpdatePlayerStatisticsRequest
  - PlayFabId (string) - Identifiant PlayFab du joueur dont les statistiques sont mises à jour.
  - Statistics (StatisticUpdate[]) - Statistiques à mettre à jour, avec les valeurs fournies.
- UpdatePlayerStatisticsResult (aucun paramètre).

​Statistiques et classements

​Configuration des statistiques réinitialisables

​Statistiques préexistantes

​Réinitialisation manuelle d’une statistique

​Quand la réinitialisation a lieu

​Lecture et écriture des versions de statistiques

​Requête serveur

​Réponse du serveur

​Requête client

​Réponse du client

​Requête serveur

​Réponse du serveur

​Requête client

​Réponse du client

​Ressources

​Énumérations de base

​Classes de base et leurs membres

​Méthodes de l’API Admin

​Méthodes de l’API client

​Méthodes de l’API Server

Statistiques et classements

Configuration des statistiques réinitialisables

Statistiques préexistantes

Réinitialisation manuelle d’une statistique

Quand la réinitialisation a lieu

Lecture et écriture des versions de statistiques

Requête serveur

Réponse du serveur

Requête client

Réponse du client

Requête serveur

Réponse du serveur

Requête client

Réponse du client

Ressources

Énumérations de base

Classes de base et leurs membres

Méthodes de l’API Admin

Méthodes de l’API client

Méthodes de l’API Server