Passer au contenu principal

​
Intégration de place de marché : Microsoft Store

Ce tutoriel vous montre comment échanger des achats intégrés du Microsoft Store (y compris sur XBOX) au moyen de PlayFab Economy v2 à l’aide de l’API RedeemMicrosoftStoreInventoryItems. À la fin de ce tutoriel, vous aurez :
  • Créé une extension dans Partner Center
  • Configuré les paramètres requis dans Partner Center et dans PlayFab
  • Lié votre produit du Microsoft Store à un ensemble (Bundle) du catalogue PlayFab
  • Appelé l’API d’échange et vérifié les articles dans l’inventaire de votre joueur

​
Prérequis

  1. Un compte Partner Center ayant accès à votre application.
  2. Une application déjà créée dans Partner Center.
  3. Un titre déjà créé dans Game Manager.
  4. Le joueur qui appelle l’API d’échange doit être authentifié auprès de PlayFab avec une identité XBOX Live (par exemple, au moyen de LoginWithXbox). Les joueurs authentifiés avec d’autres types d’identité (comme CustomID ou une adresse courriel) ne disposent pas du contexte XBOX requis pour ce flux.

​
Types de produits pris en charge

L’API RedeemMicrosoftStoreInventoryItems prend en charge les types de produits suivants du Microsoft Store :
  • Consommable géré par le développeur — Produits qui peuvent être achetés, utilisés, puis achetés de nouveau (par exemple, des lots de monnaie de jeu). Le service du jeu est responsable du suivi de l’exécution.
  • Durable — Produits achetés une seule fois et possédés de façon permanente (par exemple, du contenu téléchargeable, des extensions de jeu, des passes saisonnières ou des articles cosmétiques).
Les consommables gérés par le Store ne sont pas pris en charge. PlayFab Economy v2 ne peut pas échanger les consommables gérés par le Store. Si votre extension est configurée comme consommable géré par le Store, l’API d’échange retourne une réponse HTTP 200 avec des résultats vides et aucune erreur, ce qui rend le problème difficile à diagnostiquer.

​
Étape 1 : Créer votre extension dans Partner Center

  1. Connectez-vous à Partner Center et accédez à votre application.
  2. Sous Add-ons, sélectionnez Create a new add-on.
  3. Sélectionnez le type de produit approprié :
    • Consommable géré par le développeur pour les articles qui peuvent être rachetés (monnaie, lots de consommables).
    • Durable pour les achats uniques (contenu téléchargeable, passes saisonnières, déverrouillages cosmétiques).
  4. Terminez la configuration de l’extension (prix, descriptions, etc.) et soumettez-la.
Lors de la création d’un consommable géré par le développeur, Partner Center affiche un avertissement qui indique : « XBOX exige que les consommables soient gérés; n’utilisez donc pas cette option et créez plutôt une extension de type “managed consumable”. Si vous avez des questions, communiquez avec votre représentant Microsoft. »* Cet avertissement reflète les directives générales de la plateforme XBOX et ne s’applique pas au flux d’échange de PlayFab. Les consommables gérés par le développeur fonctionnent correctement sur XBOX lorsqu’ils sont utilisés avec l’API RedeemMicrosoftStoreInventoryItems de PlayFab. Vous pouvez poursuivre sans crainte avec ce type de produit.
  1. Après avoir créé votre extension, notez le Store ID, soit la chaîne alphanumérique (par exemple, 9NBLGGH42CFD) affichée dans Partner Center. Utilisez cette valeur pour PlayFab, et non le Product ID défini par le développeur ni le nom de l’extension.
Pour plus d’information sur les types de produits, consultez Choisir le bon type de produit.

​
Étape 2 : Configurer le Product Group, le Dev Studio et le Business Partner ID

Cette étape configure le flux de jeton délégué du service de jeton de sécurité XBOX (XSTS) que PlayFab utilise pour interroger l’API Collections du Microsoft Store au nom du joueur.
La configuration du Product Group, du Dev Studio et du Business Partner ID est l’étape la plus souvent oubliée. Sans elle, l’appel à l’API d’échange réussit (HTTP 200), mais l’API Collections retourne zéro article, ce qui donne des tableaux Succeeded, Failed et TransactionIds vides sans aucun message d’erreur.
  1. Dans Partner Center, accédez à Developer Settings > XBOX Live > Web Services et générez un certificat Business Partner si ce n’est pas déjà fait.
  2. Accédez à Developer Settings > XBOX Live > Business Partner et notez le Business Partner ID qui correspond au service Web auquel votre partie de confiance est associée.
  3. Créez un Dev Studio (ou utilisez-en un existant) et définissez son Dev Studio ID pour qu’il corresponde au Business Partner ID de l’étape 2. Si le Dev Studio possède déjà un ID différent, créez un nouveau Dev Studio plutôt que de modifier la valeur existante. La modifier peut briser des services existants.
  4. Créez un Product Group et attribuez-le au Dev Studio de l’étape 3.
  5. Ajoutez votre produit de jeu et toutes vos extensions à la liste Included in this product group. Les articles doivent être explicitement déplacés du côté « available » vers le côté « included ».
  6. Sélectionnez Save.
  7. Accédez à la page XBOX Settings de votre jeu et confirmez que le Business Partner lié correspond à celui de l’étape 2.
  8. Republiez votre produit de jeu et toutes les extensions dans le Microsoft Store, dans votre sandbox cible ou dans l’environnement RETAIL.
Pour la procédure de configuration complète, consultez Configurer les produits avec l’authentification déléguée (jetons XSTS).

​
Étape 3 : Activer l’extension XBOX Network dans Game Manager

L’extension XBOX Network lie votre produit Partner Center à votre titre PlayFab et active la validation des jetons XBOX pour l’échange dans le Microsoft Store.
  1. Ouvrez Game Manager et sélectionnez votre titre.
  2. Sélectionnez Add-ons dans le menu de navigation de gauche.
  3. Repérez et sélectionnez l’extension XBOX Network (libellée Distribute for XBOX).
  4. Sélectionnez le bon Seller ID dans la liste déroulante. Si vous ne voyez pas le bon Seller ID, sélectionnez Sign in with a different partner center account.
  5. Sélectionnez votre Partner Center Product ID dans la liste déroulante et confirmez que le XBOX Live Title ID (décimal) correspond à ce que vous voyez dans Partner Center sous XBOX services > XBOX Settings.
  6. Sélectionnez Install XBOX Network pour enregistrer la configuration.
Pour plus de détails, consultez Configuration de l’extension XBOX Live.
Game Manager comporte aussi une page d’extension Microsoft Store distincte (également sous Add-ons). Bien qu’elle ne nécessite aucune configuration, elle contient des directives utiles, notamment la confirmation des types de produits pris en charge et des détails sur la configuration du Dev Studio ID et du Business Partner ID.

​
Étape 4 : Créer un ensemble PlayFab avec un mappage de place de marché

Pour lier votre produit du Microsoft Store à votre catalogue PlayFab, créez un ensemble (Bundle) avec un mappage de place de marché (Marketplace Mapping) (AlternateId).
  1. Dans Game Manager, accédez à Economy > Catalog (V2) > Bundles.
  2. Sélectionnez New bundle (ou modifiez un ensemble existant).
  3. Dans la section Marketplace Mapping, ajoutez un nouveau mappage :
    • Définissez le Marketplace type à MicrosoftStore (sensible à la casse, doit être exactement MicrosoftStore).
    • Définissez la valeur au Store ID exact provenant de Partner Center (par exemple, 9NBLGGH42CFD). N’utilisez pas le Product ID défini par le développeur ni le nom de l’extension.
  4. Ajoutez les articles que le joueur doit recevoir lorsque cet ensemble est échangé (par exemple, de la monnaie de jeu ou des articles virtuels).
  5. Publiez l’ensemble. Les ensembles non publiés (brouillons) ne sont pas mis en correspondance lors de l’échange.
Pour plus d’information sur les ID alternatifs, consultez ID alternatifs.

​
Étape 5 : Obtenir et fournir le jeton XBOX

Lors de l’appel à l’API RedeemMicrosoftStoreInventoryItems, vous devez fournir un jeton XBOX valide dans le paramètre XboxToken.
  • Si vous utilisez l’API C du GDK, utilisez :
Les trois paramètres (méthode, URL et corps) doivent être fournis exactement comme indiqué. Un jeton obtenu incorrectement fait échouer silencieusement la requête à l’API Collections, qui retourne des résultats vides sans erreur.

​
Étape 6 : Tester l’intégration

Avant de considérer votre intégration comme terminée, vérifiez le flux complet de bout en bout :
  1. Assurez-vous que votre extension est publiée dans la sandbox ou l’environnement dans lequel vous effectuez les tests.
  2. Connectez-vous comme joueur de test avec une identité XBOX Live et effectuez un achat de test de l’extension dans le Microsoft Store. Le joueur doit avoir un achat non échangé dans son compte pour que l’API d’échange ait quelque chose à détecter.
  3. Appelez RedeemMicrosoftStoreInventoryItems avec le XboxToken du joueur.
  4. Vérifiez que la réponse contient des entrées dans le tableau Succeeded et que les articles correspondants apparaissent dans l’inventaire PlayFab du joueur.
Exécution des consommables gérés par le développeur : Après l’échange d’un consommable géré par le développeur, PlayFab le signale automatiquement comme exécuté (consommé) auprès du Microsoft Store en votre nom. L’étape d’exécution est nécessaire avant que le joueur puisse acheter de nouveau le consommable. Si le consommable n’apparaît pas comme exécuté après un échange réussi, relancez l’appel RedeemMicrosoftStoreInventoryItems. Si le problème persiste, signalez-le à l’équipe PlayFab par votre canal de soutien. Pour plus de détails, consultez Gestion des consommables et des remboursements.

​
Résolution des problèmes

Si l’appel RedeemMicrosoftStoreInventoryItems réussit (HTTP 200), mais que les tableaux Succeeded, Failed et TransactionIds de la réponse sont tous vides, l’API Collections du Microsoft Store ne trouve aucun article correspondant à échanger. Ce comportement est généralement causé par un problème de configuration. Vérifiez les éléments suivants : Si l’API retourne une erreur HTTP (comme 400), vérifiez la réponse d’erreur pour les codes suivants :
Si l’appel réussit (HTTP 200), mais retourne des résultats vides alors que toute la configuration semble correcte, vérifiez d’abord la configuration du Product Group. L’étape du Product Group est celle qui est le plus souvent oubliée.

​
Remarque sur les titres PC / Windows

Ce tutoriel couvre le flux XBOX, qui utilise des jetons XSTS délégués (transmis au moyen du paramètre XboxToken). Pour les titres PC / Windows, Microsoft recommande plutôt d’utiliser des User Store ID avec Microsoft Entra ID pour l’authentification de service à service. Pour plus d’information, consultez Demander un User Store ID pour l’authentification de service à service et Authentifier votre service — User Store ID.

​
Voir aussi

Dernière modification le 6 octobre 2026