Passer au contenu principal

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

Ce tutoriel vous montre comment échanger des achats intégrés Microsoft Store (y compris XBOX) via 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 PlayFab
  • Lié votre produit Microsoft Store à un Bundle du catalogue PlayFab
  • Appelé l’API Redeem et vérifié les éléments 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 Redeem doit être authentifié auprès de PlayFab avec une identité XBOX Live (par exemple, via LoginWithXbox). Les joueurs authentifiés avec d’autres types d’identité (comme CustomID ou une adresse e-mail) 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 Microsoft Store suivants :
  • Consommable géré par le développeur — Produits pouvant être achetés, utilisés, puis rachetés (par exemple, des packs de monnaie du 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, des DLC, des packs d’extension, des passes saisonniers ou des éléments 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 Redeem renvoie 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 Extensions, sélectionnez Créer une extension.
  3. Sélectionnez le type de produit approprié :
    • Consommable géré par le développeur pour les éléments pouvant être rachetés (monnaie, packs de consommables).
    • Durable pour les achats uniques (DLC, passes saisonniers, déblocages cosmétiques).
  4. Terminez la configuration de l’extension (tarification, descriptions, etc.) et soumettez-la.
Lors de la création d’un consommable géré par le développeur, Partner Center affiche un avertissement indiquant : « XBOX exige que les consommables soient gérés ; n’utilisez donc pas cette option et créez plutôt une extension de type “consommable géré”. Si vous avez des questions, contactez votre représentant Microsoft. »* Cet avertissement reflète les recommandations générales de la plateforme XBOX et ne s’applique pas au flux d’échange 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 en toute sécurité avec ce type de produit.
  1. Après avoir créé votre extension, notez le Store ID, 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 ou le nom de l’extension.
Pour plus d’informations 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 jetons délégués XBOX Security Token Service (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 Redeem réussit (HTTP 200), mais l’API Collections ne renvoie aucun élément, ce qui produit des tableaux Succeeded, Failed et TransactionIds vides sans 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 correspondant au service web auquel votre partie de confiance est lié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 perturber les 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 éléments 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 vérifiez que le Business Partner lié correspond à celui de l’étape 2.
  8. Republiez votre produit de jeu et toutes les extensions sur le Microsoft Store dans votre sandbox cible ou dans l’environnement RETAIL.
Pour la procédure de configuration complète, consultez Configurer des 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 Microsoft Store.
  1. Ouvrez Game Manager et sélectionnez votre titre.
  2. Sélectionnez Add-ons dans le menu de navigation de gauche.
  3. Recherchez et sélectionnez l’extension XBOX Network (intitulé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 vérifiez que le XBOX Live Title ID (décimal) correspond à celui affiché 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 dispose également d’une page d’extension Microsoft Store distincte (également sous Add-ons). Bien qu’elle ne nécessite aucune configuration, elle contient des informations 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 Bundle PlayFab avec un mappage de place de marché

Pour lier votre produit Microsoft Store à votre catalogue PlayFab, créez un 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 bundle existant).
  3. Dans la section Marketplace Mapping, ajoutez un nouveau mappage :
    • Définissez le Marketplace type sur MicrosoftStore (sensible à la casse, doit être exactement MicrosoftStore).
    • Définissez la value sur le Store ID exact 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 éléments que le joueur doit recevoir lorsque ce Bundle est échangé (par exemple, de la monnaie du jeu ou des objets virtuels).
  5. Publiez le Bundle. Les Bundles non publiés (brouillons) ne sont pas pris en compte lors de l’échange.
Pour plus d’informations sur les ID alternatifs, consultez ID alternatifs.

​
Étape 5 : Obtenir et fournir le jeton XBOX

Lorsque vous appelez 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 de manière incorrecte fait échouer silencieusement la requête à l’API Collections, qui renvoie 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 en tant que joueur de test avec une identité XBOX Live et effectuez un achat de test de l’extension via le Microsoft Store. Le joueur doit disposer d’un achat non échangé sur son compte pour que l’API Redeem puisse détecter quelque chose.
  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 éléments 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. Cette étape d’exécution est nécessaire pour que le joueur puisse racheter le consommable. Si le consommable n’apparaît pas comme exécuté après un échange réussi, réessayez l’appel RedeemMicrosoftStoreInventoryItems. Si le problème persiste, faites remonter le problème à l’équipe PlayFab via votre canal de support. 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 élément correspondant à échanger. Ce comportement est généralement dû à un problème de configuration. Vérifiez les éléments suivants : Si l’API renvoie une erreur HTTP (par exemple 400), recherchez les codes suivants dans la réponse d’erreur :
Si l’appel réussit (HTTP 200) mais renvoie des résultats vides alors que tout le reste de la configuration semble correct, vérifiez d’abord la configuration du Product Group. L’étape du Product Group est la 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 via le paramètre XboxToken). Pour les titres PC / Windows, Microsoft recommande plutôt d’utiliser des User Store IDs avec Microsoft Entra ID pour l’authentification de service à service. Pour plus d’informations, consultez Demande d’un User Store ID pour l’authentification de service à service et Authentification de votre service — User Store IDs.

​
Voir aussi

Dernière modification le 6 octobre 2026