- Déterminer ce que les utilisateurs peuvent acheter
- Évaluer les produits que l’utilisateur possède ou auxquels il a droit
- Acheter des produits éligibles
Préparation de l’appel des API XStore
Toutes les APIXStore fonctionnent sur un XStoreContextHandle créé à l’aide de XStoreCreateContext.
Ce contexte vous permet d’effectuer des opérations du Store dans le contexte de l’utilisateur spécifié sur console et de l’utilisateur par défaut disponible sur PC. Sur console, un événement de suspension ou de Quick Resume invalide le contexte. Pour gérer ces situations en toute sécurité, fermez le XStoreContextHandle et recréez-le chaque fois que le jeu reprend après un état suspendu.
1. Déterminer ce que les utilisateurs peuvent acheter
Ce qu’un jeu propose généralement à l’achat, ce sont ses extensions. Le code suivant illustre l’appel d’API XStoreQueryAssociatedProductsAsync de base nécessaire pour que le jeu sache quels produits sont disponibles. Cette requête renvoie automatiquement uniquement les extensions achetables associées au jeu. Des produits non liés associés au même éditeur (c’est-à-dire configurés avec le même compte Partner Center) peuvent également être renvoyés par cet appel, à condition que le jeu soit défini avec une relation « peut vendre » envers ce produit dans la section Configuration des relations de produit de Partner Center. Pour en savoir plus sur la configuration des relations de produit, consultez Configurer les relations de produit pour un jeu.Points à noter
- Seuls les produits achetables sont renvoyés avec
XStoreQueryAssociatedProductsAsync; les produits qui ne sont accordés que dans des offres groupées ou qui ne sont pas définis comme achetables indépendamment ne sont pas renvoyés. Pour ces derniers, utilisezXStoreQueryProductsAsync. - Le nombre de produits renvoyés n’est pas connu à l’avance ; le décompte doit donc être cumulé.
Pagination
La gestion de la pagination n’est pas facultative lors de l’interrogation des produits associés ou des droits d’utilisation. Le nombre de pages renvoyées par le service, ainsi que le nombre d’éléments renvoyés par page, peuvent varier selon les environnements et la charge du service. Pour un exemple de gestion de la pagination, consultez XStoreQueryAssociatedProductsAsync.Autres options
XStoreQueryProductsAsync peut être utilisée pour interroger des produits spécifiques, si lestoreId est connu ou si d’autres actionFilters sont souhaités. Les « actions » sont des scénarios d’utilisation qui s’appliquent à un produit, notamment des verbes comme Purchase, License, Gift et Redeem.
XStoreQueryAssociatedProductsForStoreIdAsync peut être utilisée pour interroger les produits associés à d’autres jeux, ce qui peut être utile pour proposer en vente croisée les extensions d’un autre titre.
XStoreQueryProductForCurrentGameAsync permet d’interroger uniquement le produit du jeu en cours d’exécution.
XStoreShowAssociatedProductsUIAsync fait passer l’utilisateur à l’application Microsoft Store, sur une vue des produits associés filtrée par type de produit. Cette API est une alternative à l’énumération des produits disponibles pour les présenter dans une interface du jeu.

2. Évaluer les produits que l’utilisateur possède ou auxquels il a droit
Cette étape fait appel en grande partie au même code que celui présenté précédemment, mais avec ces remplacements :- XStoreQueryAssociatedProductsAsync → XStoreQueryEntitledProductsAsync
- XStoreQueryAssociatedProductsResult → XStoreQueryEntitledProductsResult
QueryEntitledProducts renvoient les produits auxquels l’utilisateur a droit. Avoir droit signifie que l’utilisateur possède directement le produit, qu’il satisfait le droit d’utilisation par le biais d’autres produits (comme des offres groupées et des abonnements), ou qu’il obtient le droit d’utilisation par le biais d’un droit d’utilisation partagé par un autre utilisateur.
De plus, les résultats de XStoreQueryAssociatedProductsAsync (et des fonctions associées) déterminent le droit d’utilisation. La structure XStoreProduct contient un champ isInUserCollection défini sur true lorsque l’utilisateur dispose du droit d’utilisation.
Possession des consommables
La quantité de consommables est indiquée dansXStoreProduct.skus[i].collectionData.quantity. En général, il n’existe qu’une seule référence (SKU) pour un produit consommable.
Vous pouvez également utiliser XStoreQueryConsumableBalanceRemainingAsync pour connaître la quantité, mais évitez de l’utiliser individuellement pour un grand nombre de consommables, car chaque appel entraîne un appel de service.
Pour préserver l’intégrité des écosystèmes basés sur les consommables, utilisez la validation et l’échange des consommables côté service. Pour plus d’informations, consultez Écosystèmes basés sur les consommables.
Possession des produits durables
Il ne suffit pas de vérifier si le compte possède le produit pour déterminer qu’il doit avoir le droit de l’utiliser dans le jeu. Les produits durables doivent respecter la stratégie de partage de contenu décrite dans Modèle de partage de produits pour les jeux. Utilisez XStoreAcquireLicenseForPackageAsync pour un durable avec package afin de déterminer s’il peut faire l’objet d’une licence selon les règles de partage de contenu. Utilisez XStoreAcquireLicenseForDurablesAsync pour un durable sans package afin de faire de même. Utilisez XStoreQueryAddOnLicensesAsync pour un jeu sous licence numérique afin de renvoyer la liste des produits durables sans package pouvant faire l’objet d’une licence. Pour plus d’informations, consultez Gérer et accorder une licence au contenu téléchargeable et Comment utiliser un durable sans package.3. Acheter des produits éligibles
Pour afficher le flux d’achat d’un produit achetable, transmettez lestoreId à l’API XStoreShowPurchaseUIAsync :
Documentation de référence des API
- XStore (contenu de l’API)
- Fonctions
- XStoreCreateContext
- XStoreQueryAssociatedProductsAsync
- XStoreQueryProductsAsync
- XStoreQueryAssociatedProductsForStoreIdAsync
- XStoreQueryProductForCurrentGameAsync
- XStoreShowAssociatedProductsUIAsync
- XStoreQueryEntitledProductsAsync
- XStoreQueryAssociatedProductsResult
- XStoreQueryEntitledProductsResult
- XStoreQueryConsumableBalanceRemainingAsync
- XStoreAcquireLicenseForPackageAsync
- XStoreAcquireLicenseForDurablesAsync
- XStoreQueryAddOnLicensesAsync
- XStoreShowPurchaseUIAsync
- Structures
- Fonctions
