> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Intégration de PlayFab pour les titres utilisant les services XBOX

> Connectez les joueurs aux services XBOX et à PlayFab, provisionnez des comptes liés et mettez en place les achats dans l'application du Microsoft Store par l'économie PlayFab pour les titres GDK.

PlayFab est le backend en tant que service (backend-as-a-service) de Microsoft pour les jeux en ligne : économie, catalogues, classements, CloudScript, analytique, matchmaking et réseau voix/données PlayFab Party. Il s'intègre proprement par-dessus les services XBOX. Les services XBOX détiennent l'**identité visible par le joueur** (gamertag, amis, succès, présence, sessions MPSD), tandis que PlayFab détient les **données du service en ligne côté backend** (inventaire, monnaie, données utilisateur personnalisées, télémétrie).

Tout titre GDK qui utilise **PlayFab Party**, l'économie PlayFab pour les **achats dans l'application du Microsoft Store**, les classements PlayFab ou tout autre service PlayFab doit connecter le joueur aux **deux** piles et maintenir le lien entre les deux identités.

> [!NOTE]
>
> Cette page se concentre sur la partie XBOX de l'intégration : comment provisionner un compte PlayFab lié à l'XUser connecté, et comment le flux des droits (entitlements) du Microsoft Store s'articule avec l'économie PlayFab. Pour l'ensemble des fonctionnalités de PlayFab (Game Manager, catalogues, CloudScript, matchmaking, Party), consultez la [documentation PlayFab](https://learn.microsoft.com/gaming/services/playfab/).

## Comptes utilisateur XBOX et PlayFab

Un compte des services XBOX et un compte PlayFab sont deux identités distinctes :

* **Compte des services XBOX** : visible par le joueur. Appartient au compte Microsoft (MSA) du joueur. Porte le gamertag, le XUID, les amis, les succès et la présence.
* **Compte PlayFab** : en arrière-plan. Identifié par un **Entity ID** au sein de votre **TitleId PlayFab** (une chaîne de 4 à 6 chiffres hexadécimaux attribuée lorsque vous créez un titre dans [PlayFab Game Manager](https://developer.playfab.com/)). Il ne s'agit pas de votre ID de titre XBOX.

Pour utiliser une fonctionnalité PlayFab (chat vocal Party, économie, classements) dans votre titre GDK, chaque XUser connecté doit disposer d'un compte PlayFab lié, provisionné dans le contexte de votre titre PlayFab. À la fin du flux de connexion :

* Le joueur a été ajouté avec `XUserAddAsync` et dispose d'un `XUserHandle`.
* Un compte PlayFab existe pour ce joueur sous votre TitleId PlayFab (provisionné automatiquement lors de la première connexion).
* Les comptes XBOX et PlayFab sont liés, et le titre détient des informations d'identification valides (Entity ID + jeton PlayFab) pour les appels REST/SDK PlayFab authentifiés.

> [!WARNING]
>
> Votre **TitleId PlayFab n'est pas identique à votre ID de titre XBOX**. Provisionnez un titre PlayFab par jeu (ou par partition) dans PlayFab Game Manager et codez ce TitleId en dur dans la configuration de votre build.

## Connecter les joueurs à PlayFab

Deux chemins de connexion sont pris en charge. Choisissez-en un en fonction des services PlayFab que vous utilisez :

> [card] [PlayFab Services SDK](#playfab-services-sdk-recommended)
>
> **Recommandé pour tous les titres.** Fourni sous forme de bibliothèque d'extension de jeu (Gaming Extension Library) (`PlayFab.Services.C`) dans le GDK. À utiliser pour l'économie, les classements, CloudScript, le matchmaking et tout titre qui utilise **plus que Party**.

> [card] Bibliothèque d'assistance Xbox Live de PlayFab Party
>
> À utiliser uniquement si **PlayFab Party est le seul service PlayFab** que vous utilisez et que les services XBOX sont votre seul fournisseur d'authentification. Fournie avec le SDK PlayFab Party dans le GDK.

### PlayFab Services SDK (recommandé)

Le PlayFab Services SDK est fourni avec le GDK et expose `PFAuthenticationLoginWithXUserAsync`, qui prend un `XUserHandle` et connecte le joueur à PlayFab en un seul appel. Définissez `createAccount = TRUE` pour provisionner automatiquement le compte PlayFab lié lors de la première exécution.

**Configuration**

1. Installez le [GDK](https://aka.ms/gdkdl).
2. Ajoutez la bibliothèque d'extension de jeu **PlayFab.Services.C** à votre projet :
   * Ouvrez le projet dans Visual Studio → **Project** → **Properties**.
   * Sous **Configuration Properties** → **Gaming Desktop** → **General**, ouvrez **Gaming Extension Libraries** et ajoutez **PlayFab.Services.C**.

**Flux de connexion recommandé**

1. Connectez le joueur à son compte XBOX avec [`XUserAddAsync`](https://docs.xbox.com/fr-CA/reference/system/xuser/xuser_members) et conservez le `XUserHandle` retourné.
2. Appelez `PFAuthenticationLoginWithXUserAsync` :
   * Passez le `XUserHandle` comme paramètre `user`.
   * Définissez `createAccount = TRUE` pour que PlayFab provisionne automatiquement un compte lié lors de la première connexion.
3. Conservez les informations d'identification PlayFab obtenues (Entity ID + jeton PlayFab) pour la session et utilisez-les pour tous les appels PlayFab suivants.

Consultez le [démarrage rapide du PlayFab Services SDK pour le GDK](https://learn.microsoft.com/gaming/services/playfab/sdks/gdk/quickstart) pour la procédure complète.

### Bibliothèque d'assistance XBOX Live de PlayFab Party

Si PlayFab Party est le **seul** service PlayFab utilisé par votre titre, vous pouvez vous passer du PlayFab Services SDK et vous connecter par la bibliothèque d'assistance XBOX Live de Party, fournie avec le SDK PlayFab Party dans le GDK.

**Flux**

1. Connectez le joueur à XBOX avec `XUserAddAsync`.
2. Lors de la première initialisation du chat, récupérez le XUID avec `XUserGetId`.
3. Créez un **`PartyXblLocalChatUser`** en appelant `PartyXblManager::CreateLocalChatUser` avec le XUID.
4. Appelez `PartyXblManager::LoginToPlayFab` avec cet objet utilisateur.
   * Sur le GDK (console et PC) et le XDK, la bibliothèque d'assistance récupère en interne le jeton des services XBOX requis, connecte le joueur à PlayFab à l'aide de ses informations d'identification XBOX et crée automatiquement un compte PlayFab lors de la première connexion. Les comptes ainsi créés n'ont ni adresse courriel ni nom d'utilisateur associés.
   * Sur les titres non GDK/non XDK (par exemple, PC Win32 sans GDK), vous recevez à la place un `PartyXblTokenAndSignatureRequestedStateChange`. Récupérez vous-même le jeton des services XBOX et renvoyez-le par `PartyXblManager::CompleteGetTokenAndSignatureRequest`.
5. En cas de réussite, vous recevez un `PartyXblLoginToPlayFabCompletedStateChange` contenant l'Entity ID et le jeton PlayFab.

> [!NOTE]
>
> Pour les utilisateurs **distants**, utilisez `PartyXblManager::CreateRemoteChatUser` : aucune authentification ni aucun échange de jeton n'est nécessaire pour le flux des utilisateurs distants.

## XUser est le pont d'identité

Tout ce qui suit (connexion à PlayFab, jetons d'écriture de session MPSD, appels S2S, requêtes de droits) commence par un `XUserHandle` retourné par `XUserAddAsync`. Deux API sont importantes pour l'intégration de PlayFab :

| API | Objectif |
| - | - |
| [`XUserAddAsync`](https://docs.xbox.com/fr-CA/reference/system/xuser/xuser_members) | Connecter le joueur à son compte XBOX et obtenir un `XUserHandle`. |
| `XUserGetTokenAndSignatureUtf16Async` | Récupérer un jeton + une signature des services XBOX pour le chemin de la bibliothèque d'assistance (solution de repli Win32) ou pour tout pont S2S personnalisé. |

Consultez [Identité des services XBOX](https://docs.xbox.com/fr-CA/services/xbox-services/fundamentals/identity/xs-identity-overview.md) pour le modèle de connexion plus large (MSA, jetons XSTS, portée des bacs à sable).

## Titres multiplateformes

PlayFab prend en charge de nombreux fournisseurs d'authentification de plateforme. Lorsque vous publiez le même titre sur iOS, Android, Steam ou PlayStation, n'essayez **pas** de faire passer chaque joueur par XUser : utilisez le fournisseur d'authentification PlayFab natif de la plateforme :

* **iOS** : Apple ID (`LoginWithApple`).
* **Android** : Google Play Games (`LoginWithGoogleAccount`).
* **Steam** : `LoginWithSteam`.
* **XBOX / GDK PC** : `PFAuthenticationLoginWithXUserAsync` (cette page).

Chaque connexion de plateforme provisionne son propre compte PlayFab et le lie au même titre PlayFab. Les identités liées des joueurs qui passent d'une plateforme à l'autre avec le même compte PlayFab sont fusionnées dans PlayFab.

Consultez [Authentification PlayFab propre à chaque plateforme](https://learn.microsoft.com/gaming/services/playfab/features/authentication/platform-specific-authentication/) pour la matrice complète.

## Achats dans l'application du Microsoft Store par l'économie PlayFab

Pour les titres GDK qui vendent des éléments dans l'application par le Microsoft Store, PlayFab sert de **backend d'économie** tandis que le Microsoft Store gère la transaction proprement dite. PlayFab rapproche les achats du Microsoft Store de l'inventaire PlayFab du joueur à l'aide de la **méthode des droits** : le joueur doit d'abord être connecté à son compte XBOX.

### Le flux

1. Le joueur est connecté à XBOX (`XUserAddAsync`) et à PlayFab (`PFAuthenticationLoginWithXUserAsync`).
2. Le joueur achète un élément par le Microsoft Store sur l'appareil.
3. Votre titre informe PlayFab de l'achat.
4. PlayFab appelle [`ConsumeMicrosoftStoreEntitlements`](https://learn.microsoft.com/rest/api/services/playfab/client/platform-specific-methods/consume-microsoft-store-entitlements) avec le jeton XBOX et synchronise l'inventaire PlayFab du joueur, en lui accordant les nouveaux éléments.

> [!WARNING]
>
> Pour les titres GDK, utilisez le module complémentaire PlayFab **Microsoft Store** et `ConsumeMicrosoftStoreEntitlements`. N'utilisez **pas** l'ancien module complémentaire XBOX / `ConsumeXboxEntitlements` (ce chemin est réservé aux titres XDK). Le module complémentaire Universal Windows Platform est déprécié.

### Prérequis dans Partner Center

* Être inscrit au [XBOX Creators Program](https://www.xbox.com/developers/creators-program) ou être un partenaire géré.
* Disposer d'une identité d'éditeur configurée dans Partner Center avec le même GUID d'éditeur que vos informations de partenaire commercial XBOX (`aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee`).
* Disposer de l'approbation du concept pour utiliser les services XBOX.

Dans Partner Center, sous **Game setup → XBOX services**, choisissez **Use full XBOX services feature set (requires concept approval)** ou **Use XBOX Creators Program**, puis créez vos extensions sous votre titre.

> [!NOTE]
>
> Le module complémentaire Microsoft Store de PlayFab **ne prend pas en charge les consommables gérés par le Store** dans Partner Center. Créez uniquement des **consommables gérés par le développeur** (ou des durables).

### Créer des éléments correspondants dans Partner Center et PlayFab

Le **Product ID** de Partner Center et l'**Item ID** de PlayFab doivent correspondre exactement pour que la synchronisation des droits fonctionne.

1. Dans Partner Center → **Add-ons** → **Create a new Consumable (Developer-managed)** (ou Durable). Entrez un **Product ID** unique (par exemple, `MyItem_001`).
2. Dans [PlayFab Game Manager](https://developer.playfab.com/) → **Engage** → **Economy** → **New item**. Entrez la même chaîne dans **Item ID** (`MyItem_001`). Marquez-le comme Consumable ou Durable pour correspondre à Partner Center, puis enregistrez.

### Référence terminologique

| Concept | PlayFab | Partner Center / Microsoft Store |
| - | - | - |
| Identificateur unique | Item ID | Product ID |
| Consommable | Consumable | Consumable (Developer-managed) |
| Durable | Durable | Durable *ou* Durable with packages |
| Boutique virtuelle en jeu | Store | *(n/a)* |

### Catalogues et boutiques : un seul Item ID au niveau global

PlayFab vous permet de définir plusieurs **catalogues** par titre et, au sein de chaque catalogue, de regrouper des éléments dans des **boutiques** (Stores). Pour que la synchronisation des droits du Microsoft Store fonctionne, **chaque Product ID doit correspondre à exactement un Item ID dans l'ensemble des versions de catalogue de votre titre PlayFab.**

> [!WARNING]
>
> Si le même `Item ID` apparaît dans plusieurs catalogues, la consommation des droits échouera. Veillez à ce que les ID d'élément soient uniques au niveau global dans tous les catalogues d'un titre PlayFab donné.

**Incorrect : même ID réutilisé dans plusieurs catalogues :**

| Version du catalogue | Item ID | Type |
| - | - | - |
| MyCatalog\_001 | MyItem\_001 | Consumable |
| MyCatalog\_002 | MyItem\_001 | Consumable |
| MyCatalog\_003 | MyItem\_001 | Durable |

**Correct : un seul Item ID par SKU, librement réutilisé dans les boutiques :**

| Version du catalogue | Item ID | Type |
| - | - | - |
| MyCatalog\_001 | MyItem\_001 | Consumable |
| MyCatalog\_001 | MyItem\_002 | Durable |
| MyCatalog\_002 | MyItem\_003 | Consumable |
| MyCatalog\_003 | MyItem\_004 | Durable |

Les boutiques d'un catalogue peuvent ensuite regrouper librement n'importe quel sous-ensemble de ces éléments uniques :

| ID de la boutique | Item IDs |
| - | - |
| MyStore\_001 | MyItem\_001, MyItem\_002 |
| MyStore\_002 | MyItem\_001 |
| MyStore\_003 | MyItem\_002, MyItem\_003, MyItem\_004 |

## Voir aussi

* [Identité des services XBOX](https://docs.xbox.com/fr-CA/services/xbox-services/fundamentals/identity/xs-identity-overview.md) : XUser, MSA, jetons XSTS, portée des bacs à sable.
* [Multijoueur XBOX](https://docs.xbox.com/fr-CA/services/xbox-services/multiplayer/index.md) : PlayFab Party comme option de transport multijoueur.
* [Game Chat 2](https://docs.xbox.com/fr-CA/services/xbox-services/multiplayer/chat/game-chat2/game-chat-2-intro.md) : Game Chat 2 superposé à PlayFab Party.
* [Multiplayer Activity](https://docs.xbox.com/fr-CA/services/xbox-services/multiplayer/mpa/live-mpa-overview.md) : intégration de MPA + PlayFab Party.
* [Démarrage rapide du PlayFab Services SDK pour le GDK](https://learn.microsoft.com/gaming/services/playfab/sdks/gdk/quickstart)
* [Tarifs de PlayFab](https://playfab.com/pricing/)


## Related topics

- [Identity](https://docs.xbox.com/fr-CA/xbox-services/identity.md)
- [Multiplayer](https://docs.xbox.com/fr-CA/xbox-services/multiplayer.md)
- [Game Chat](https://docs.xbox.com/fr-CA/xbox-services/game-chat.md)
- [Multiplayer Activity](https://docs.xbox.com/fr-CA/xbox-services/multiplayer-activity.md)