Limitation du sandbox : lors de la consommation de produits consommables gérés par le développeur dans un sandbox de développement, seule l’authentification par jeton XSTS est prise en charge. L’authentification par User Store ID ou par Microsoft Entra ID ne fonctionne pas pour les appels de consommation de consommables gérés par le développeur dans les environnements sandbox. Planifiez vos tests en conséquence. Pour plus d’informations, consultez la section Prérequis de l’API Consume.
Utilisation de la bibliothèque .NET Microsoft.StoreServices et de l’exemple
Pour illustrer les principes et les flux décrits dans cet article, consultez l’exemple Microsoft.StoreServices, qui fournit :- L’utilisation de la bibliothèque Microsoft.StoreServices pour gérer l’authentification et effectuer les appels aux services du Microsoft Store.
- Un exemple de logique pour gérer les produits consommables, suivre les demandes de consommation en attente, rapprocher les achats remboursés, renouveler les User Store ID expirés, et plus encore.
- Un guide de configuration qui comprend les étapes de cet article sur la façon de configurer et de mettre en place votre Microsoft Entra ID pour cette méthode d’authentification.
- Microsoft.StoreServices (GitHub)
- Exemple Microsoft.StoreServices (GitHub)
Gestion des consommables
Structure recommandée d’un service de gestion des consommables
Utilisez un flux serveur unique pour valider la propriété, exécuter l’utilisation et rapprocher les remboursements. La structure suivante rend ces responsabilités explicites et sécuritaires en cas de nouvelle tentative.Gestion du solde de l’utilisateur dans votre service par rapport au Microsoft Store
Les produits consommables gérés par le Store peuvent être entièrement gérés dans votre service de jeu en consommant tout solde non nul dans le Microsoft Store. Le solde de consommables de l’utilisateur peut aussi être géré par le Microsoft Store, la quantité n’étant consommée que lorsqu’elle est utilisée pour des articles dans le jeu. Les produits consommables gérés par le développeur, en revanche, doivent être gérés dans un service de jeu. Consultez Choisir le bon type de produit pour plus d’informations sur les consommables gérés par le développeur par rapport à ceux gérés par le Microsoft Store. L’approche la plus courante consiste à suivre le solde effectif de monnaie de l’utilisateur dans votre service. Dans cette conception, votre service interroge les soldes de consommables non nuls, les consomme et crédite l’équivalent en monnaie du jeu au compte de l’utilisateur. Ce flux réduit les appels répétés aux API du Store après l’exécution, simplifie la gestion multiplateforme des soldes et offre aux équipes de soutien un système central pour les ajustements de solde. Configuration typique : configurez chaque palier de monnaie comme un consommable distinct géré par le Store qui octroie une quantité de1 par achat, puis associez chaque produit à sa valeur dans le jeu. Exemple : un consommable « 500 pièces » fait passer la quantité dans le Store à 1; après la consommation, la quantité dans le Store revient à 0 et votre service crédite 500 pièces.
Les consommables gérés par le Store peuvent octroyer la valeur complète directement à la quantité du Store lors de l’achat (par exemple, 500 par achat). Dans ce modèle, le Store suit la croissance du solde et votre service déduit la quantité lorsque les utilisateurs dépensent de la monnaie dans le jeu. Toutefois, placer tous les paliers comme SKU sous un même ID de produit limite certaines fonctionnalités, comme les prix promotionnels propres à un palier et les jetons d’échange 5x5. Consultez Meilleures pratiques pour offrir de la monnaie dans le jeu.
Utiliser les TrackingId comme système redondant de validation de la consommation
Incluez unTrackingId dans chaque demande de consommation. Si une réponse est perdue, réessayez avec les mêmes TrackingId, utilisateur, productId et quantité pour confirmer si la consommation initiale a réussi. Cette nouvelle tentative empêche les doubles octrois tout en permettant des nouvelles tentatives sécuritaires.
Le flux suivant présente un modèle de consommation sécuritaire en cas de nouvelle tentative.
Le produit A (500 pièces dans le jeu) est un consommable configuré pour octroyer une quantité de 1 dans le Store.
- L’utilisateur achète le produit A et possède maintenant une quantité de
1pour le produit lors de l’appel au service de requête. - Le service du jeu interroge le solde de consommables de l’utilisateur au moyen de l’API de requête du Microsoft Store et constate que le solde de l’utilisateur est de
1. - Le service du jeu génère un TrackingID, crée une demande de consommation pour consommer une unité du produit et ajoute les informations de la demande à une liste de transactions en attente.
- Le service du jeu envoie la demande à l’API de consommation du Microsoft Store.
- Le service du jeu ne reçoit pas de réponse de l’API de consommation (perte de paquets réseau, panne de service, panne de courant, etc.). À ce stade, le service ne peut pas confirmer si la transaction a été effectuée. Interroger uniquement l’inventaire peut être ambigu si l’utilisateur a racheté le produit pendant la panne. Utilisez la liste des transactions en attente et réessayez avec les mêmes valeurs de demande.
- Le service du jeu détermine quand il doit réessayer la demande de consommation.
- Le service du jeu recrée la demande de consommation avec les mêmes utilisateur, ProductId, TrackingId et quantité.
- Le service du jeu envoie la demande à l’API de consommation du Microsoft Store.
- Le service du jeu reçoit une réponse indiquant que la demande a réussi et que le nouveau solde de l’utilisateur est de « 0 ».
- Le service du jeu ajoute 500 pièces au solde de monnaie de l’utilisateur suivi sur le serveur.
- Le service du jeu retire la demande de consommation de la liste des transactions en attente, puisque l’article a été consommé et vérifié, et que l’utilisateur a reçu la bonne monnaie du jeu dans le service.
Comportement de l’API Consume du Microsoft Store lors de la vérification de demandes de transaction antérieures
Si une demande arrive avec des valeurs différentes, l’API la traite comme une nouvelle demande de consommation. Si l’API détecte une nouvelle tentative avec les mêmesTrackingId, utilisateur, quantité et productId, elle ne consomme pas une deuxième fois. Elle retourne plutôt une réponse réussie avec le solde restant actuel. Grâce à ce comportement, la relecture d’une demande ayant expiré est sécuritaire tant que les valeurs de la demande sont identiques.
Si vous utilisez l’authentification X-Token pour l’API de consommation, vous pouvez mettre à jour et obtenir un nouveau X-Token, à condition que le nouveau X-Token concerne le même utilisateur XBOX que la demande précédente.
Atténuer la fraude liée aux retours et aux remboursements de consommables à l’aide du service d’événements Clawback
Pour aider à prévenir les abus et les retours ou remboursements frauduleux de produits consommables, votre service doit utiliser le service d’événements Clawback. Clawback permet à votre service de recevoir des événements lorsqu’un produit consommable est retourné ou remboursé. Votre service doit alors retirer la valeur ajoutée au compte de l’utilisateur pour ce consommable. Pour agir sur les événements Clawback, assurez-vous d’utiliser l’option"includeOrderIds": TRUE dans votre demande de consommation à collections.mp.microsoft.com/v8.0/collections/consume. Votre service doit stocker les données des transactions de consommation provenant des réponses de l’API à l’aide des variables suivantes :
Mettez en place cette base de données de suivi tôt, de préférence avant l’intégration à la file Clawback. Les données recueillies tôt vous donnent un historique des transactions pour le rapprochement futur et une base de référence propre pour mesurer les effets du traitement Clawback.
Pour plus d’informations, consultez Gestion des remboursements et des rétrofacturations à partir de votre service.