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 associé
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 inclut les étapes de cet article sur la configuration de 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é, traiter l’utilisation et rapprocher les remboursements. La structure suivante rend ces responsabilités explicites et sûres en cas de nouvelle tentative.Gestion du solde de l’utilisateur sur votre service ou dans le Microsoft Store
Les produits consommables gérés par le Store peuvent être entièrement gérés sur votre service de jeu en consommant tout solde non nul dans le Microsoft Store. Le solde de consommables de l’utilisateur peut également être géré via 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 nécessitent en revanche une gestion sur 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 et ceux gérés par le Microsoft Store. L’approche la plus courante consiste à suivre le solde de devise effectif de l’utilisateur sur votre service. Dans cette conception, votre service interroge les soldes de consommables non nuls, les consomme et crédite l’équivalent en devise du jeu sur le compte de l’utilisateur. Ce flux réduit les appels répétés aux API du Store après le traitement, simplifie la gestion multiplateforme des soldes et offre aux équipes de support un système central pour les ajustements de solde. Configuration typique : configurez chaque palier de devise comme un consommable géré par le Store distinct 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 dans la quantité du Store lors de l’achat (par exemple, 500 par achat). Dans ce modèle, le Store suit l’augmentation du solde et votre service déduit la quantité lorsque les utilisateurs dépensent de la devise dans le jeu. Toutefois, placer tous les paliers en tant que 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 Bonnes pratiques pour proposer une devise de jeu.
Utiliser les TrackingIds 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 d’origine a réussi. Cette nouvelle tentative évite les doubles octrois tout en permettant de réessayer en toute sécurité.
Le flux suivant illustre un modèle de consommation sûr 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 dispose désormais d’une quantité de
1pour ce produit lors de l’appel au service de requête. - Le service du jeu interroge le solde de consommables de l’utilisateur via 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 n’obtient pas de réponse de l’API de consommation (perte de paquets réseau, panne de service, coupure de courant, etc.). À ce stade, le service ne peut pas confirmer si la transaction a abouti. 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 devise de l’utilisateur suivi sur le serveur.
- Le service du jeu supprime la demande de consommation de la liste des transactions en attente, car l’article a été consommé et vérifié, et l’utilisateur a reçu la bonne devise de jeu sur le service.
Comportement de l’API Consume du Microsoft Store lors de la vérification des demandes de transaction précédentes
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 renvoie plutôt une réponse de réussite avec le solde restant actuel. Grâce à ce comportement, rejouer une demande ayant expiré est sûr tant que les valeurs de la demande sont identiques.
Si vous utilisez l’authentification X-Token pour l’API de consommation, vous pouvez actualiser 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énuation de la fraude aux retours et remboursements de consommables avec le service d’événements Clawback
Pour éviter 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 du compte de l’utilisateur pour ce consommable. Pour agir sur les événements Clawback, veillez à 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 issues 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 d’attente Clawback. Des données précoces vous fournissent un historique des transactions pour les futurs rapprochements 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 depuis votre service.