Ajout d'évaluations à votre contenu - XBOX Game Development Documentation

Economy v2 est maintenant en disponibilité générale. Pour obtenir du soutien et transmettre vos commentaires, rendez-vous sur le forum PlayFab.

Ce guide présente les appels d’API qui peuvent être utilisés pour ajouter un système d’évaluations et de critiques à votre jeu.

Évaluer un article

Une évaluation ou une critique peut être associée à un article en appelant l’API ReviewItem à partir d’un client. Pour qu’un article puisse être évalué, il doit être visible dans le catalogue public pour tous les joueurs. Les évaluations et les critiques sont associées au joueur qui appelle l’API, et une seule critique par joueur peut être associée à un article. Le créateur d’un article ne peut pas soumettre de critique pour son propre article. La critique est mise à jour chaque fois que ReviewItem est appelée. Les données suivantes sont obligatoires pour l’appel :

Id : L’ID unique de l’article à évaluer.
Rating : Une évaluation numérique sur une échelle de 1 à 5.

De plus, des paramètres facultatifs peuvent également être ajoutés :

Title : Le titre de la critique.
ReviewText : Un champ de texte libre pour les critiques.
IsInstalled : Un indicateur précisant si l’auteur de la critique possède l’article.
ItemVersion : Le numéro de version de l’article évalué.

{
  "Review": {
    "ItemVersion": "2.4.1",
    "Rating": 5,
    "Title": "Best Game Ever",
    "ReviewText": "I play this game every day. It's my favorite game yet.",
    "IsInstalled": true
  },
  "Id": "3f5dd8d4-4ee1-4748-8855-56a8a0277bf9"
}

Un horodatage Submitted est automatiquement renseigné et mis à jour lorsqu’une critique est soumise.

Obtenir la critique d’un joueur pour un article

Vous pouvez obtenir la critique d’un joueur pour un article en appelant l’API GetEntityItemReview à partir d’un client. Un Id ou un AlternateId d’article doit être fourni. Un ReviewId précis associé à la critique sera retourné.

{
    "code": 200,
    "status": "OK",
    "data": {
        "Review": {
            "ReviewId": "730de69c-d6af-f313-4653-09fb14bedeef",
            "ItemId": "3f5dd8d4-4ee1-4748-8855-56a8a0277bf9",
            "ReviewerId": "title_player_account!218870DE55036998",
            "ItemVersion": "2.4.1",
            "Title": "Best Game Ever",
            "ReviewText": "I play this game every day. It's my favorite game yet.",
            "Rating": 5,
            "IsInstalled": true,
            "Locale": "NEUTRAL",
            "HelpfulnessVotes": 0,
            "HelpfulPositive": 0,
            "HelpfulNegative": 0,
            "Submitted": "2021-08-09T06:44:22.569Z"
        }
    }
}

L’appel de GetEntityItemReview par un joueur qui n’a pas rédigé de critique retourne un objet Review avec des valeurs à zéro :

{
    "code": 200,
    "status": "OK",
    "data": {
        "Review": {
            "ReviewId": "00000000-0000-0000-0000-000000000000",
            "Rating": 0,
            "IsInstalled": false,
            "HelpfulnessVotes": 0,
            "HelpfulPositive": 0,
            "HelpfulNegative": 0,
            "Submitted": "0001-01-01T00:00:00Z"
        }
    }
}

Obtenir les critiques d’un article

Vous pouvez accéder à toutes les critiques contenant du texte pour un article en appelant l’API GetItemReviews. Un Id ou un AlternateId d’article doit être fourni. Des paramètres facultatifs peuvent être ajoutés :

ContinuationToken : Un jeton opaque utilisé pour récupérer la page suivante d’articles, le cas échéant.
Count : Le nombre d’articles à récupérer. La taille de page maximale est de 200. S’il n’est pas précisé, la valeur par défaut est 10.
OrderBy : Un orderBy OData utilisé pour trier les résultats de la requête. Les valeurs possibles sont Helpfulness, Rating et Submitted.

{
  "Count": 2,
  "Id": "3f5dd8d4-4ee1-4748-8855-56a8a0277bf9",
  "OrderBy": "Submitted desc"
}

Soumettre un vote d’utilité pour une critique

Les joueurs peuvent soumettre un vote d’utilité pour une critique en appelant l’API SubmitItemReviewVote. La soumission d’un nouveau vote d’utilité incrémente HelpfulPositive ou HelpfulNegative selon la valeur booléenne du paramètre Vote.

{
  "ReviewId": "730de69c-d6af-f313-4653-09fb14bedeef",
  "Vote": "Helpful/UnHelpful"
}

Signaler une critique

Les joueurs peuvent signaler une critique en appelant l’API ReportItemReview à partir d’un client. Un ReviewId doit être fourni. Un paramètre facultatif ConcernCategory peut être ajouté.

{
  "ReviewId": "730de69c-d6af-f313-4653-09fb14bedeef",
  "ConcernCategory": "OffensiveContent"
}

S’il n’est pas précisé, ConcernCategory prend la valeur par défaut None. Les valeurs valides de ConcernCategory sont les suivantes :

None
OffensiveContent
ChildExploitation
MalwareOrVirus
PrivacyConcerns
MisleadingApp
PoorPerformance
ReviewResponse
SpamAdvertising
Profanity

L’appel de ReportItemReview déclenche uniquement un événement PlayStream sous le nom d’événement item_reported. Effectuez vos requêtes à l’aide de l’Explorateur de données dans Game Manager. Des exemples de requêtes sont présentés ci-dessous : La requête suivante retourne le nombre total de signalements par ConcernCategory pour chaque ItemId au cours des 3 derniers jours

['events.all']
| where Timestamp > ago (3d)
| where FullName_Name == "review_reported"
| project ReviewId = tostring(EventData.Payload.ReviewId), ConcernCategory = tostring(EventData.Payload.ConcernCategory)
| summarize TotalReportCount = count() by ReviewId, ConcernCategory
| sort by TotalReportCount desc
| render columnchart kind=stacked

Retirer une critique

Vous pouvez soumettre une demande de retrait d’une ou de plusieurs critiques à l’aide de l’API TakedownItemReviews. Cette API ne peut être appelée que par l’entité de titre. L’appel accepte un ensemble de critiques à retirer.

{
  "Reviews": [
    {
      "ItemId": "3f5dd8d4-4ee1-4748-8855-56a8a0277bf9",
      "ReviewId": "730de69c-d6af-f313-4653-09fb14bedeef"
    }
  ]
}

En raison du traitement de la demande, un délai pouvant aller jusqu’à 24 heures peut s’écouler avant qu’une critique soit retirée

Conception et mise en cache des évaluations

Nous offrons deux méthodes pour obtenir les évaluations. La différence entre les deux approches tient au fait que vous interagissez directement avec la critique ou avec l’article du catalogue.

Nous fournissons les évaluations directement (au moyen de GetItemReviews, etc.)
Nous fournissons des agrégats d’évaluations dans les articles du catalogue (au moyen de SearchItems, etc.)

Les deux approches sont asynchrones et comportent des délais qu’il est important de comprendre.

Évaluations directes (GetItemReviews, etc.)

Toutes ces évaluations et critiques sont fournies directement. Il existe deux catégories de latence ici.

Critiques individuelles - Quasi en temps réel
Les critiques individuelles ne seront pas disponibles immédiatement, mais devraient apparaître en quelques secondes. Nous estimons que de nouvelles tentatives avec un délai progressif suffiront pour lire une toute nouvelle critique.
Évaluations agrégées - Moins de 15 minutes Il existe un cache pour les agrégats

Évaluations des articles du catalogue (SearchItems, etc.)

Toutes ces évaluations sont fournies dans le cadre de l’article du catalogue à partir de notre catalogue publié.

Évaluations agrégées - Moins de 8 heures
Le système agrège les évaluations et transmet les mises à jour au catalogue. Les mises à jour peuvent prendre de 4 à 8 heures.

​Évaluer un article

​Obtenir la critique d’un joueur pour un article

​Obtenir les critiques d’un article

​Soumettre un vote d’utilité pour une critique

​Signaler une critique

​Retirer une critique

​Conception et mise en cache des évaluations

​Évaluations directes (GetItemReviews, etc.)

​Évaluations des articles du catalogue (SearchItems, etc.)

Évaluer un article

Obtenir la critique d’un joueur pour un article

Obtenir les critiques d’un article

Soumettre un vote d’utilité pour une critique

Signaler une critique

Retirer une critique

Conception et mise en cache des évaluations

Évaluations directes (GetItemReviews, etc.)

Évaluations des articles du catalogue (SearchItems, etc.)