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

# Prise en charge multiplateforme de XUser

> Prise en charge multiplateforme de XUser

## Vue d'ensemble

XUser est l'API Gaming Runtime permettant de gérer les comptes d'utilisateur XBOX et l'authentification sur toutes les plateformes. Elle fournit une interface unifiée permettant aux jeux de gérer la connexion des utilisateurs, l'identité et les flux utilisateur connexes sur les consoles XBOX, les PC et appareils portables Windows, ainsi que sur des plateformes non Microsoft comme le Steam Deck.

Dans le cadre de l'initiative multiplateforme du GDK, XUser offre une surface d'API cohérente sur toutes les plateformes tout en tenant compte des capacités et des contraintes propres à chaque environnement.

### Exigences d'intégration

Pour utiliser XUser dans votre jeu, incluez `XUser.h` dans vos fichiers sources et effectuez l'édition de liens avec `XGameRuntime.lib`. La principale différence entre les plateformes réside dans la façon dont les dépendances d'exécution sont gérées :

#### Consoles XBOX et Microsoft Store / Game Pass sur Windows

Le Gaming Runtime est intégré au système d'exploitation et géré par le magasin. Votre jeu utilise automatiquement les services et l'interface utilisateur intégrés du système.

#### Autres magasins sur Windows

* Les jeux utilisent les services et l'interface utilisateur intégrés du système d'exploitation.
* Le programme d'installation doit exécuter **GamingRepair.exe** pour s'assurer que le service Gaming Runtime est installé.

**Intégration de l'outil Gaming Repair**

Ajoutez l'outil Gaming Repair au programme d'installation de votre jeu en tant qu'étape d'installation personnalisée :

1. **Incluez l'outil dans le package de votre jeu** – Il est inclus avec le GDK à l'emplacement `[GDK]\bin\GamingRepair.exe`.
2. **Ajoutez une action personnalisée** – Exécutez l'outil avant l'installation de votre jeu (par exemple : start /wait "Installing Gaming Services" GamingRepair.exe scenarioExternal). Cela vérifie, télécharge, installe ou répare tous les composants Gaming Runtime manquants.
3. **Gérez les erreurs** – Vérifiez le code de sortie de l'outil. En cas d'échec, avisez l'utilisateur et fournissez des instructions d'installation manuelle.

<Info>
  Les jeux Steam doivent inclure `XGameRuntime.dll` et ses dépendances pour prendre en charge les plateformes où le service système n'est pas disponible (par exemple, le Steam Deck).
  Sur le Steam Deck ou d'autres plateformes non Microsoft, l'outil Gaming Repair ne peut pas être utilisé. Regroupez plutôt `XGameRuntime.dll` et ses dépendances dans le package de votre jeu et placez-les à côté de votre exécutable afin qu'ils puissent être chargés à l'exécution.
</Info>

## Différences entre plateformes et API unifiée

Sur XBOX et Windows, le système d'exploitation gère nativement la connexion XBOX Live et la gestion des utilisateurs, en fournissant une interface utilisateur système et un stockage sécurisé des informations d'identification des utilisateurs. XUser tire parti de ces services système intégrés sur ces plateformes. Sur d'autres plateformes de jeu comme le Steam Deck ou des environnements tiers, cette prise en charge native n'existe pas.

À partir de la version GDK 2510, XUser a été amélioré pour fonctionner de façon transparente sur les deux types de plateformes au moyen d'une API cohérente, avec de nouvelles API et des modèles pilotés par les événements qui permettent aux jeux de fournir l'interface utilisateur et la gestion des données nécessaires là où la prise en charge système n'est pas disponible :

* **Sur les plateformes avec prise en charge native (XBOX, Windows)** - XUser utilise les services intégrés du système d'exploitation pour l'authentification, l'interface utilisateur et le stockage des informations d'identification. Les jeux appellent les API XUser, et le système gère les détails automatiquement.

* **Sur les plateformes sans prise en charge native (Steam Deck, etc.)** - XUser expose les mêmes API principales, mais les jeux doivent implémenter des gestionnaires d'événements pour fournir l'interface utilisateur nécessaire (comme l'affichage de codes QR pour la connexion) et le stockage des données. Cela donne aux jeux un contrôle total sur l'expérience d'authentification.

Quelle que soit la plateforme, les jeux obtiennent un `XUserHandle` qui représente le joueur et qui peut être utilisé pour les services prenant en charge l'authentification XBOX (XBOX services, services PlayFab, etc.)

## Nouvelles capacités multiplateformes

Les nouvelles API introduites pour XUser visent à permettre des flux de connexion et une gestion des données indépendants de la plateforme. Les principales capacités comprennent :

### Authentification Remote Connect

Permet aux utilisateurs de se connecter avec leur compte XBOX sur un appareil (comme le Steam Deck) à l'aide d'un appareil secondaire. Les utilisateurs peuvent balayer un code QR ou entrer un code à usage unique sur un site Web pour terminer l'authentification. Cela est réalisé au moyen de nouveaux gestionnaires d'événements XUser servant à afficher et à fermer les invites de connexion par code.

### Application de la session unique (SPoP)

Garantit que les utilisateurs n'exécutent pas le même jeu à plusieurs endroits simultanément. Si un conflit est détecté, les utilisateurs sont invités à choisir entre « jouer ici » ou « changer de compte ». De nouvelles API permettent aux jeux de présenter ce choix et d'y répondre en conséquence.

<Note>
  Sur les consoles XBOX et Windows, le système d'exploitation continue de gérer automatiquement la plupart des tâches d'authentification. Le jeu pourrait ne jamais voir ces événements sur ces plateformes. Toutefois, sur les plateformes autres que XBOX, le jeu peut prendre le contrôle total au moyen des mécanismes de rappel de XUser.
</Note>

## Remote Connect pour la connexion entre appareils

Remote Connect est une fonctionnalité qui permet aux joueurs de se connecter à leur compte XBOX sur un appareil en s'authentifiant au moyen d'un autre appareil (comme un téléphone ou un PC). Cela se fait généralement au moyen d'un code court ou d'un code QR affiché par le jeu.

### Fonctionnement

Sur les consoles XBOX, ce « flux par code » est géré automatiquement par l'interface utilisateur du système. Toutefois, sur des plateformes comme le Steam Deck ou d'autres environnements tiers, il n'existe aucune interface de connexion XBOX gérée par le système. L'API Remote Connect de XUser permet aux jeux de faciliter directement ce flux.

#### Le flux

1. **Inscription du gestionnaire d'événements** - Le jeu inscrit un gestionnaire d'événements Remote Connect avant de lancer la connexion à l'aide de `XUserPlatformRemoteConnectSetEventHandlers(...)`. Le titre fournit des rappels pour gérer deux événements clés :

   * **Événement Show** - Déclenché lorsque XUser a besoin que le jeu affiche le code à usage unique ou le code QR. Le gestionnaire présente une boîte de dialogue ou une superposition contenant le code et les instructions (par exemple : « Balayez ce code QR ou visitez xbox.com/play et entrez le code ABCD pour vous connecter »).

   * **Événement Close** - Déclenché lorsque le processus de connexion à distance est terminé ou annulé, signalant au jeu de masquer ou de fermer la boîte de dialogue du code.

2. **Lancement de la connexion de l'utilisateur** - Lors de l'appel à `XUserAddAsync` pour ajouter un nouvel utilisateur, si aucun utilisateur local n'est déjà connecté, le système XUser peut utiliser le flux Remote Connect (particulièrement sur les plateformes sans affichage ou tierces).

3. **Affichage du code** - XUser invoque le rappel « show », en fournissant le code d'authentification ou l'URL. Le gestionnaire d'interface utilisateur du jeu (comme `OnRemoteConnectShow`) affiche le code QR ou la chaîne de code à l'utilisateur.

4. **Authentification de l'utilisateur** - Le joueur utilise son téléphone ou son navigateur Web pour se connecter avec le code fourni, liant ainsi son compte XBOX à la session en cours.

5. **Achèvement** - Une fois l'authentification terminée sur le serveur principal, XUser invoque le rappel « close », signalant que le code peut être retiré de l'écran. À ce stade, XUser a obtenu le jeton XBOX Live de l'utilisateur et crée le `XUserHandle`.

6. **Réussite** - La tâche `XUserAddAsync` se termine avec succès, et l'utilisateur est connecté sans avoir entré ses informations d'identification directement sur l'appareil.

### Implémentation

Pour utiliser Remote Connect, implémentez deux fonctions de rappel et inscrivez-les :

```cpp theme={null}
XUserPlatformRemoteConnectEventHandlers remoteConnect = {};
remoteConnect.context = nullptr;
remoteConnect.show = &OnRemoteConnectShow;   // Display QR/code dialog
remoteConnect.close = &OnRemoteConnectClose; // Dismiss dialog

HRESULT hr = XUserPlatformRemoteConnectSetEventHandlers(nullptr, &remoteConnect);
```

Après avoir inscrit les gestionnaires, appelez `XUserAddAsync` comme d'habitude pour ajouter un nouvel utilisateur. Dans le gestionnaire `OnRemoteConnectShow`, récupérez les informations fournies (accessibles au moyen des API XUser, généralement une URL et un code) et affichez-les pour l'utilisateur dans une fenêtre contextuelle ou une superposition. Lorsque `OnRemoteConnectClose` est appelé, le processus de connexion est terminé et le jeu doit masquer l'invite.

<Info>
  Appelez `XUserPlatformRemoteConnectSetEventHandlers` avant d'appeler `XUserAddAsync` (et généralement avant `XUserInitialize`) pour vous assurer que ces événements sont gérés correctement.
</Info>

### Considérations relatives à l'expérience utilisateur

Pour offrir une bonne expérience utilisateur :

* **Instructions claires** - Expliquez clairement ce que l'utilisateur doit faire lors de l'affichage du code.
* **Gestion des erreurs** - Si l'utilisateur annule du côté distant ou qu'une erreur se produit, XUser fera échouer la tentative de connexion. Gérez ce cas dans le rappel d'achèvement normal de `XUserAddAsync`.
* **Fermeture rapide** - Masquez le code immédiatement lorsque l'événement de fermeture se produit afin d'éviter toute confusion chez l'utilisateur.
* **Conception visuelle** - Assurez-vous que le code QR et les instructions sont suffisamment grands et clairement visibles sur l'appareil cible.

## Application de la session unique (SPoP)

L'application de la session unique, ou SPoP (Single Point of Presence), est une politique qui garantit qu'un même profil d'utilisateur XBOX Live n'exécute pas le même titre simultanément sur plusieurs appareils. Par exemple, si vous lancez un jeu sur votre PC alors qu'il est déjà en cours d'exécution sous votre compte sur XBOX, une session doit être suspendue ou déconnectée afin d'éviter les conflits de sauvegardes de jeu et d'autres problèmes.

Sur les consoles XBOX, ce scénario déclenche une boîte de dialogue système indiquant à l'utilisateur que le jeu est déjà en cours d'exécution ailleurs et lui demandant s'il souhaite continuer (ce qui le déconnecterait de l'autre appareil). Sur les plateformes non Microsoft, il n'existe aucun mécanisme intégré pour appliquer cette règle. L'API d'invite SPoP de XUser permet aux jeux de détecter cette situation et de présenter au joueur le choix « Jouer ici ou Changer de compte ».

### Fonctionnement

L'API SPoP utilise un modèle de gestionnaire d'événements semblable à celui de Remote Connect. Lorsqu'un conflit de connexion est détecté, XUser invoque le gestionnaire du jeu au lieu d'échouer directement, ce qui permet au jeu de présenter des options à l'utilisateur.

#### Le flux

1. **Inscription du gestionnaire d'événements** - Le jeu inscrit un gestionnaire d'événements d'invite SPoP avant de lancer la connexion à l'aide de `XUserPlatformSpopPromptSetEventHandlers(...)`.

2. **Détection des conflits** - Lors de l'appel à `XUserAddAsync` pour ajouter un utilisateur, si XUser détecte que le même utilisateur est déjà actif ailleurs dans le même titre, il invoque le gestionnaire SPoP.

3. **Affichage de l'invite** - Le gestionnaire du jeu reçoit le gamertag moderne de l'utilisateur et un handle d'opération. Le gestionnaire doit afficher une invite d'interface utilisateur comme : « \[Gamertag] joue déjà sur un autre appareil. Voulez-vous plutôt jouer ici (ce qui entraînera la déconnexion sur l'autre appareil) ou changer de compte? » avec des options comme « Jouer ici » et « Changer de compte ».

4. **Choix de l'utilisateur** - Le jeu attend que l'utilisateur fasse une sélection. L'opération reste en attente jusqu'à ce que le jeu appelle l'API d'achèvement.

5. **Achèvement de l'opération** - Selon le choix de l'utilisateur, le jeu appelle `XUserPlatformSpopPromptComplete` avec le résultat approprié :

   * **Jouer ici** - `XUserPlatformSpopOperationResult::SignInHere` - Connecte l'utilisateur sur cet appareil et met fin à la session distante.
   * **Changer de compte** - `XUserPlatformSpopOperationResult::SwitchAccount` - Annule la connexion sur cet appareil, ce qui permet à l'utilisateur de choisir un autre compte.
   * **Annuler** - `XUserPlatformSpopOperationResult::Canceled` - Abandonne la tentative de connexion.

6. **Résolution** - XUser poursuit selon le résultat. Si « Jouer ici » a été choisi, la session distante prend fin (l'autre appareil reçoit un événement de déconnexion) et l'utilisateur devient actif localement. Si « Changer de compte » a été choisi, `XUserAddAsync` échoue et le jeu peut demander un autre compte.

### Implémentation

Pour utiliser SPoP, implémentez une fonction de rappel et inscrivez-la :

```cpp theme={null}
HRESULT hr = XUserPlatformSpopPromptSetEventHandlers(nullptr, &OnSpopPrompt, nullptr);
```

Dans le gestionnaire `OnSpopPrompt`, le jeu reçoit l'identificateur de l'utilisateur et son gamertag moderne. Le gestionnaire doit mettre en pause le déroulement du jeu (puisque la connexion est en attente) et présenter une invite d'interface utilisateur avec les options. Le gestionnaire stocke le handle d'opération et ne le termine pas immédiatement.

Lorsque l'utilisateur fait un choix :

```cpp theme={null}
// If user chose "Play here"
XUserPlatformSpopPromptComplete(operation, XUserPlatformSpopOperationResult::SignInHere);

// If user chose "Switch account"
XUserPlatformSpopPromptComplete(operation, XUserPlatformSpopOperationResult::SwitchAccount);

// If dialog was canceled
XUserPlatformSpopPromptComplete(operation, XUserPlatformSpopOperationResult::Canceled);
```

<Info>
  * Appelez `XUserPlatformSpopPromptSetEventHandlers` avant d'appeler `XUserAddAsync` pour vous assurer que les conflits sont gérés correctement.
  * Vous devez appeler `XUserPlatformSpopPromptComplete` exactement une fois pour chaque événement SPoP reçu, sinon la connexion restera bloquée indéfiniment.
  * Si aucun gestionnaire n'est défini et qu'un conflit se produit, `XUserAddAsync` échouera avec un code d'erreur, sans donner à l'utilisateur la possibilité de résoudre le conflit de façon harmonieuse.
</Info>

### Considérations relatives à l'expérience utilisateur

Pour offrir une bonne expérience utilisateur :

* **Messages clairs** - Affichez le gamertag de l'utilisateur et expliquez clairement que continuer le déconnectera de l'autre appareil.
* **Options visibles** - Rendez les options « Jouer ici » et « Changer de compte » clairement visibles et compréhensibles.
* **Prévention des conflits de sauvegarde** - Insistez sur le fait que cela évite les conflits de sauvegardes de jeu et les problèmes de jeu simultané.
* **Comportement propre à la plateforme** - Sur XBOX et Windows, le système d'exploitation gère cela automatiquement et le gestionnaire SPoP ne sera jamais invoqué. Sur les autres plateformes, votre jeu est responsable de présenter ce choix.

Sans cette API, les conflits de connexion entraîneraient des erreurs obscures ou des déconnexions automatiques sans avertissement, ce qui nuirait à l'expérience utilisateur. L'invite SPoP rend le comportement explicite et piloté par l'utilisateur, conformément à la politique de session unique de XBOX, tout en donnant le contrôle aux joueurs.

## Voir aussi

[Identité de l'utilisateur et XUser](/fr-CA/build/core-features/common/user/player-identity-xuser)


## Related topics

- [Conseils de conception multijoueur multiplateforme](/fr-CA/services/xbox-services/multiplayer/overviews/multiplayer-design-guidance-cross-platform.md)
- [Vue d'ensemble de l'authentification et de l'accès aux comptes](/fr-CA/services/xbox-services/fundamentals/identity/auth/live-authentication-overview.md)
- [XUserIsStoreUser](/fr-CA/reference/system/xuser/functions/xuserisstoreuser.md)
- [XUserGetMaxUsers](/fr-CA/reference/system/xuser/functions/xusergetmaxusers.md)
- [XUserFindUserById](/fr-CA/reference/system/xuser/functions/xuserfinduserbyid.md)