Skip to main content
XBOX One gère l’identité des utilisateurs qui interagissent avec le jeu au moyen d’un objet XUser. Chaque instance XUser représente un utilisateur connecté au jeu. Chaque utilisateur est représenté par XUserHandle. Les jeux peuvent effectuer les opérations suivantes à l’aide de XUserHandle.
  • Interroger l’état de connexion aux services XBOX.
  • Récupérer le gamertag des utilisateurs.
  • Récupérer l’image de joueur des utilisateurs.
  • Déterminer la tranche d’âge des utilisateurs.
  • Déterminer les privilèges accordés à l’utilisateur, par exemple s’il est autorisé à participer à des communications en temps réel ou à des sessions multijoueurs.
  • Récupérer un jeton authentifié.

​
Identificateurs XUser

Deux identificateurs différents sont associés à un XUser donné : l’ID local et l’ID des services XBOX (XUID). L’ID local est un identificateur qui reste associé à l’utilisateur pendant toute la durée de vie de cet utilisateur dans la session de jeu. Utilisez l’ID local dans tous les processus que le jeu lance ou si le jeu appelle XLaunchNewGame. Toutefois, n’utilisez pas
l’ID local pour identifier un utilisateur d’une session de jeu à l’autre. Pour obtenir l’ID local d’un utilisateur, utilisez la fonction XUserGetLocalId. L’ID des services XBOX (XUID) est l’identificateur qui doit être utilisé lors des communications avec les services XBOX ou lors de l’appel d’une interface utilisateur appelable par le titre (TCUI). Pour obtenir le XUID d’un utilisateur, utilisez la fonction XUserGetId. Le consentement de l’utilisateur peut être nécessaire pour obtenir le XUID. Si ce consentement est requis et n’est pas accordé, XUserGetId renvoie E_GAMEUSER_RESOLVE_USER_ISSUE_REQUIRED. Pour résoudre le problème et recueillir le consentement, les jeux doivent alors appeler XUserResolveIssueWithUiAsync.

​
États XUser

Les utilisateurs peuvent se trouver dans l’un des trois états suivants : connectés aux services XBOX, en cours de déconnexion des services XBOX ou complètement déconnectés. Les jeux peuvent interroger cet état pour un utilisateur donné à l’aide de la fonction XUserGetState. Les jeux peuvent également s’inscrire aux notifications de modification à l’aide de la fonction XUserRegisterForChangeEvent. Ne jugez pas la connectivité réseau en fonction de l’état XUser. Si XUserState est SignedIn, cela indique qu’à un moment donné, l’utilisateur a été authentifié auprès des services XBOX et peut être traité comme un utilisateur actif. Toutefois, le réseau peut ne pas être connecté.

​
Ajout ou suppression d’utilisateurs dans le jeu

Contrairement au modèle de l’ERA XBOX One, un jeu ne peut interagir qu’avec les utilisateurs qu’il a demandés en appelant la fonction XUserAddAsync. Par exemple, supposons que deux utilisateurs sont connectés à la console : l’utilisateur A et l’utilisateur B.
  1. Quelqu’un lance le jeu. Dans ce scénario, peu importe qui l’a fait.
  2. Le jeu s’inscrit aux modifications d’état des utilisateurs à l’aide de XUserRegisterForChangeEvent.
  3. Le jeu appelle XUserAddAsync, et l’utilisateur A se connecte au jeu.
  4. Le jeu dispose maintenant d’un XUserHandle qui représente l’utilisateur A.
  5. Depuis le guide, l’utilisateur B choisit de se déconnecter.
  6. Aucun événement de modification de connexion n’est déclenché pour le jeu. Le jeu n’a jamais eu connaissance de l’utilisateur B.
  7. Depuis le guide, l’utilisateur A choisit de se déconnecter.
  8. Le jeu reçoit un événement de modification indiquant d’abord que l’utilisateur A est en cours de déconnexion, puis, finalement, un autre événement indiquant que l’utilisateur A est maintenant déconnecté.
Si les jeux ont la possibilité d’ajouter des utilisateurs, il n’existe que quelques façons de supprimer des utilisateurs, à l’aide de l’une des méthodes suivantes.
  • Le jeu peut fermer tous les handles qui représentent l’utilisateur à l’aide de la fonction XUserCloseHandle.
  • L’utilisateur utilise le guide pour se déconnecter de la console.
  • L’utilisateur se connecte sur un autre appareil.

​
Types d’utilisateurs

XBOX One prend en charge deux types d’utilisateurs : les joueurs XBOX et les invités. Les joueurs XBOX disposent de toutes les fonctionnalités en tant qu’utilisateurs du système. Ils sont initialement créés en ajoutant un nouveau compte dans le sélecteur de compte, une interface utilisateur fournie par le système pour connecter les utilisateurs. Les joueurs XBOX restent sur la console jusqu’à ce qu’ils soient explicitement supprimés à l’aide de l’application Paramètres. Les invités XBOX disposent d’une seule session sur une console. Ils sont créés lorsqu’ils choisissent de jouer en tant qu’invité dans le sélecteur de compte et sont parrainés par un autre joueur XBOX connecté. Les invités restent présents jusqu’à ce qu’ils se déconnectent, jusqu’à ce que le joueur XBOX parrain se déconnecte ou jusqu’à ce que la console soit éteinte. Les jeux qui souhaitent autoriser les invités doivent spécifier l’option AllowGuest lorsqu’ils appellent XUserAddAsync.

​
Modèles d’ajout d’utilisateurs

Les jeux doivent toujours tenter d’établir un utilisateur initial. Il existe deux façons principales d’y parvenir.

​
Option 1 : déterminer l’utilisateur le plus tôt possible sans afficher d’interface utilisateur

  1. Appelez XUserAddAsync à l’aide de AddDefaultUserSilently. Cette fonction tente de déterminer qui a lancé le jeu sans afficher d’interface utilisateur.
  2. L’appel à XUserAddAsync peut échouer avec E\_GAMEUSER\_NO\_DEFAULT\_USER. Dans ce cas, personne n’était connecté lors du premier lancement du jeu. Pour établir l’utilisateur initial, le jeu doit appeler XUserAddAsync sans utiliser l’indicateur AddDefaultUserSilently. Contrairement à l’option « silencieuse », cet appel garantit que tous les problèmes de consentement sont entièrement résolus et que, si l’appel réussit, l’utilisateur est connecté aux services XBOX. Le jeu peut créer un contexte XBOX pour cet utilisateur.

​
Option 2 : déterminer l’utilisateur avec la possibilité d’afficher une interface utilisateur

Appelez XUserAddAsync à l’aide de AddDefaultUserAllowingUI. Comme l’option précédente (« silencieuse »), cette fonction tente de déterminer qui a lancé le jeu. Contrairement à l’option précédente, si l’utilisateur par défaut ne peut pas être déterminé, elle affiche une interface utilisateur permettant aux joueurs de se connecter ou de se sélectionner. Si XUserAddResult réussit, le jeu dispose d’un utilisateur entièrement connecté aux services XBOX et peut créer un contexte XBOX pour cet utilisateur. Pour obtenir un exemple de code illustrant ces étapes, consultez Procédure : bonne pratique pour connecter un utilisateur.

​
Gestion de XUserHandle

Chaque XUserHandle représente un utilisateur. Toutefois, il est possible que plusieurs handles de ce type représentent chacun le même utilisateur. Les jeux doivent utiliser le modèle de base suivant.
  1. Gérez une collection d’instances XUserHandle qui représente l’ensemble des utilisateurs qui intéressent le jeu.
  2. Inscrivez-vous aux modifications d’état XUser en appelant XUserRegisterForChangeEvent. Lorsque vous constatez qu’un utilisateur est en cours de déconnexion, mettez à jour votre collection d’utilisateurs.
  3. Lorsque vous obtenez un nouveau XUserHandle à partir de XUserAddAsync, vérifiez s’il représente un nouvel utilisateur. Vous pouvez comparer directement les handles à l’aide de XUserCompare. Vous pouvez également effectuer la comparaison à l’aide de l’ID local obtenu en appelant XUserGetLocalId.
  4. Si plusieurs instances XUserHandle représentent le même utilisateur, utilisez XUserCloseHandle pour supprimer les instances en trop.
L’ID local est un identificateur qui reste associé à l’utilisateur pendant toute la durée de vie de cet utilisateur dans la session de jeu. Utilisez l’ID local dans tous les processus que le jeu lance ou si le jeu appelle XLaunchNewGame. Toutefois, n’utilisez pas l’ID local pour identifier un utilisateur d’une session de jeu à l’autre.
Last modified on October 6, 2026