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 de XUser représente un utilisateur connecté au jeu. Chaque utilisateur est représenté par XUserHandle. Les jeux peuvent faire ce qui suit à l’aide de XUserHandle.
  • Interroger l’état de connexion aux XBOX services.
  • Récupérer le gamertag des utilisateurs.
  • Récupérer l’image de joueur des utilisateurs.
  • Déterminer le groupe d’âge des utilisateurs.
  • Déterminer quels privilèges sont accordés à l’utilisateur qui 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 XBOX services (XUID). L’ID local est un identificateur qui reste associé à l’utilisateur pendant toute la durée de vie de cet utilisateur au sein de la session de jeu. Utilisez l’ID local dans tous les processus que le jeu génère 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 Xbox services (XUID) est l’identificateur qui doit être utilisé lors des communications avec les XBOX services ou lors de l’appel de l’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 requis pour obtenir le XUID. Si ce consentement est requis et n’est pas accordé, XUserGetId retourne E_GAMEUSER_RESOLVE_USER_ISSUE_REQUIRED. Pour résoudre le problème et recueillir le consentement, les jeux doivent alors appeler XUserResolveIssueWithUiAsync.

​
États de XUser

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

​
Ajout ou retrait d’utilisateurs dans le jeu

Contrairement au modèle de l’ERA de 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 changements 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. À partir du guide, l’utilisateur B choisit de se déconnecter.
  6. Aucun événement de changement de connexion n’est déclenché pour le jeu. Le jeu n’a jamais su que l’utilisateur B existait.
  7. À partir du guide, l’utilisateur A choisit de se déconnecter.
  8. Le jeu reçoit d’abord un événement de changement indiquant 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é.
Bien que les jeux aient la capacité d’ajouter des utilisateurs, il n’existe que quelques façons de retirer des utilisateurs, au moyen de l’une des méthodes suivantes.
  • Le jeu peut fermer tous les descripteurs 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 à 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 capacités d’un utilisateur sur le 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 demeurent sur la console jusqu’à ce qu’ils soient explicitement supprimés au moyen de l’application Paramètres. Les invités Xbox disposent d’une seule session sur une console. Ils sont créés lorsqu’ils choisissent, dans le sélecteur de compte, de jouer en tant qu’invité, et ils sont parrainés par un autre joueur XBOX connecté. Les invités demeurent 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 veulent 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 principales façons d’y parvenir.

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

  1. Appelez XUserAddAsync en utilisant 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 XBOX services. 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 en utilisant AddDefaultUserAllowingUI. Tout 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 XBOX services et peut créer un contexte XBOX pour cet utilisateur. Pour obtenir un exemple de code illustrant ces étapes, consultez Procédure : pratique exemplaire pour connecter un utilisateur.

​
Gestion de XUserHandle

Chaque XUserHandle représente un utilisateur. Toutefois, il est possible que plusieurs de ces descripteurs représentent chacun le même utilisateur. Les jeux doivent utiliser le modèle de base suivant.
  1. Maintenez une collection d’instances de XUserHandle qui représente la collection d’utilisateurs qui intéressent le jeu.
  2. Inscrivez-vous aux changements d’état de 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 de XUserAddAsync, assurez-vous de vérifier s’il représente un nouvel utilisateur. Vous pouvez comparer directement les descripteurs à l’aide de XUserCompare. Vous pouvez aussi les comparer à l’aide de l’ID local obtenu en appelant XUserGetLocalId.
  4. Si vous avez plusieurs instances de XUserHandle qui représentent le même utilisateur, utilisez XUserCloseHandle pour retirer les instances supplémentaires.
L’ID local est un identificateur qui reste associé à l’utilisateur pendant toute la durée de vie de cet utilisateur au sein de la session de jeu. Utilisez l’ID local dans tous les processus que le jeu génère 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