Skip to main content
XBOX One administra la identidad de los usuarios que interactúan con el juego mediante un objeto XUser. Cada instancia de XUser representa un usuario que ha iniciado sesión en el juego. Cada usuario se representa mediante XUserHandle. Los juegos pueden hacer lo siguiente mediante XUserHandle.
  • Consultar el estado de inicio de sesión en los servicios de XBOX.
  • Obtener el gamertag de los usuarios.
  • Obtener la imagen de jugador de los usuarios.
  • Determinar el grupo de edad de los usuarios.
  • Determinar qué privilegios tiene permitidos el usuario, por ejemplo, si puede participar en comunicación en tiempo real o en sesiones multijugador.
  • Obtener un token autenticado.

​
Identificadores de XUser

Hay dos identificadores diferentes asociados a un XUser determinado: el identificador local y el identificador de los servicios de XBOX (XUID). El identificador local es un identificador que permanece con el usuario durante toda la vida de ese usuario dentro de la sesión de juego. Use el identificador local en todos los procesos que genere un juego o si el juego llama a XLaunchNewGame. Sin embargo, no use el
identificador local para identificar a un usuario entre sesiones de juego. Para obtener el identificador local de un usuario, use la función XUserGetLocalId. El identificador de los servicios de Xbox (XUID) es el identificador que se debe usar al comunicarse con los servicios de XBOX o al invocar la interfaz de usuario invocable desde el título (TCUI). Para obtener el XUID de un usuario, use la función XUserGetId. Es posible que se requiera el consentimiento del usuario para obtener el XUID. Si este consentimiento es necesario y no se concede, XUserGetId devuelve E_GAMEUSER_RESOLVE_USER_ISSUE_REQUIRED. Para resolver el problema y recopilar el consentimiento, los juegos deben llamar entonces a XUserResolveIssueWithUiAsync.

​
Estados de XUser

Los usuarios pueden estar en uno de tres estados: han iniciado sesión en los servicios de XBOX, están en proceso de cerrar sesión en los servicios de XBOX o han cerrado sesión por completo. Los juegos pueden consultar este estado de un usuario especificado mediante la función XUserGetState. Los juegos también pueden registrarse para recibir notificaciones de cambio mediante la función XUserRegisterForChangeEvent. No juzgue la conectividad de red basándose en el estado de XUser. Si XUserState es SignedIn, esto indica que en algún momento el usuario se autenticó con los servicios de XBOX y se puede tratar como un usuario activo. Sin embargo, es posible que la red no esté conectada.

​
Adición o eliminación de usuarios en el juego

A diferencia del modelo de la ERA de XBOX One, un juego solo puede interactuar con los usuarios que el juego ha solicitado llamando a la función XUserAddAsync. Por ejemplo, suponga que dos usuarios han iniciado sesión en la consola: el usuario A y el usuario B.
  1. Alguien inicia el juego. Para este escenario, no importa quién lo hizo.
  2. El juego se registra para los cambios de estado de usuario mediante XUserRegisterForChangeEvent.
  3. El juego llama a XUserAddAsync y el usuario A inicia sesión en el juego.
  4. El juego ahora tiene un XUserHandle que representa al usuario A.
  5. Desde la guía, el usuario B elige cerrar sesión.
  6. No se desencadena ningún evento de cambio de inicio de sesión en el juego. El juego nunca supo del usuario B.
  7. Desde la guía, el usuario A elige cerrar sesión.
  8. El juego recibe un evento de cambio que indica primero que el usuario A está en proceso de cerrar sesión y, después, en última instancia, un evento diferente que indica que el usuario A ha cerrado sesión.
Aunque los juegos tienen la capacidad de agregar usuarios al juego, solo hay unas pocas maneras de quitar usuarios mediante uno de los métodos siguientes.
  • El juego podría cerrar todos los identificadores que representan al usuario mediante la función XUserCloseHandle.
  • El usuario usa la guía para cerrar sesión en la consola.
  • El usuario inicia sesión en un dispositivo diferente.

​
Tipos de usuarios

XBOX One admite dos tipos de usuarios: jugadores de XBOX e invitados. Los jugadores de Xbox tienen todas las capacidades como usuarios en el sistema. Se crean inicialmente al agregar una nueva cuenta en el selector de cuentas, una interfaz de usuario proporcionada por el sistema para que los usuarios inicien sesión. Los jugadores de XBOX persisten en la consola hasta que se quitan explícitamente con la aplicación de configuración. Los invitados de Xbox tienen una sesión única en una consola. Se crean cuando eligen en el selector de cuentas jugar como invitado y están patrocinados por otro jugador de XBOX con sesión iniciada. Los invitados persisten hasta que cierran sesión, hasta que el jugador de XBOX patrocinador cierra sesión o hasta que se apaga la consola. Los juegos que quieran permitir invitados deben especificar la opción AllowGuest cuando llamen a XUserAddAsync.

​
Patrones para agregar usuarios

Los juegos siempre deben intentar establecer un usuario inicial. Hay dos maneras principales de lograrlo.

​
Opción 1: determinar el usuario lo antes posible sin mostrar interfaz de usuario

  1. Llame a XUserAddAsync mediante AddDefaultUserSilently. Esta función intenta determinar quién inició el juego sin mostrar ninguna interfaz de usuario.
  2. La llamada a XUserAddAsync podría producir el error E\_GAMEUSER\_NO\_DEFAULT\_USER. Si esto sucede, nadie tenía sesión iniciada cuando el juego se inició por primera vez. Para establecer el usuario inicial, el juego debe llamar a XUserAddAsync sin usar la marca AddDefaultUserSilently. A diferencia de la opción “silenciosa”, esta llamada garantiza que todos los problemas de consentimiento se resuelvan por completo y que, si la llamada se realiza correctamente, el usuario tenga sesión iniciada en los servicios de XBOX. El juego puede crear un contexto de XBOX para ese usuario.

​
Opción 2: determinar el usuario con la posibilidad de mostrar interfaz de usuario

Llame a XUserAddAsync mediante AddDefaultUserAllowingUI. Al igual que la opción anterior (con “silencioso”), esta función intenta determinar quién inició el juego. A diferencia de la opción anterior, si no se puede determinar el usuario predeterminado, muestra la interfaz de usuario para permitir que los jugadores inicien sesión o se seleccionen a sí mismos. Si XUserAddResult se realiza correctamente, el juego tiene un usuario que ha iniciado sesión por completo en los servicios de XBOX y el juego puede crear un contexto de XBOX para ese usuario. Para ver código de ejemplo que muestra estos pasos, consulte Procedimiento: práctica recomendada para iniciar la sesión de un usuario.

​
Administración de XUserHandle

Cada XUserHandle representa un usuario. Sin embargo, es posible que varios de estos identificadores representen cada uno al mismo usuario. Los juegos deben usar el siguiente patrón básico.
  1. Mantenga una colección de instancias de XUserHandle que representen la colección de usuarios que le interesan al juego.
  2. Regístrese para los cambios de estado de XUser llamando a XUserRegisterForChangeEvent. Cuando vea que un usuario está cerrando sesión, actualice su colección de usuarios.
  3. Cuando obtenga un nuevo XUserHandle de XUserAddAsync, asegúrese de comprobar si representa a un nuevo usuario. Puede comparar directamente los identificadores mediante XUserCompare. También puede comparar mediante el identificador local que se obtiene llamando a XUserGetLocalId.
  4. Si tiene varias instancias de XUserHandle que representan al mismo usuario, use XUserCloseHandle para quitar las instancias adicionales.
El identificador local es un identificador que permanece con el usuario durante toda la vida de ese usuario dentro de la sesión de juego. Use el identificador local en todos los procesos que genere un juego o si el juego llama a XLaunchNewGame. Sin embargo, no use el identificador local para identificar a un usuario entre sesiones de juego.
Última modificación el 28 de agosto de 2026

Temas relacionados

UsuariosInformación general sobre usuarios invitadosInformación general sobre la autenticación y el acceso a cuentasXLaunchNewGameUso de la API de C++ de Game Chat 2