Skip to main content
O XBOX One gerencia a identidade dos usuários que interagem com o jogo com um objeto XUser. Cada instância de XUser representa um usuário conectado ao jogo. Cada usuário é representado por XUserHandle. Os jogos podem fazer o seguinte usando XUserHandle.
  • Consultar o estado de entrada nos XBOX services.
  • Obter o gamertag dos usuários.
  • Obter a imagem de jogador dos usuários.
  • Determinar a faixa etária dos usuários.
  • Determinar quais privilégios são permitidos para o usuário, como participar de comunicação em tempo real ou de sessões multijogador.
  • Obter um token autenticado.

​
Identificadores do XUser

Há dois identificadores diferentes associados a um determinado XUser: a ID local e a ID dos XBOX services (XUID). A ID local é um identificador que permanece com o usuário durante todo o tempo de vida desse usuário na sessão de jogo. Use a ID local em todos os processos que um jogo gerar ou se o jogo chamar XLaunchNewGame. No entanto, não use a
ID local para identificar um usuário entre sessões de jogo. Para obter a ID local de um usuário, use a função XUserGetLocalId. A ID dos XBOX services (XUID) é o identificador que deve ser usado ao se comunicar com os XBOX services ou ao invocar a interface do usuário que pode ser chamada pelo título (TCUI). Para obter a XUID de um usuário, use a função XUserGetId. Pode ser necessário o consentimento do usuário para obter a XUID. Se esse consentimento for necessário e não for concedido, XUserGetId retornará E_GAMEUSER_RESOLVE_USER_ISSUE_REQUIRED. Para resolver o problema e coletar o consentimento, os jogos devem chamar XUserResolveIssueWithUiAsync.

​
Estados do XUser

Os usuários podem estar em um de três estados: conectados aos XBOX services, em processo de saída dos XBOX services ou completamente desconectados. Os jogos podem consultar esse estado de um usuário especificado usando a função XUserGetState. Os jogos também podem se registrar para receber notificações de alteração usando a função XUserRegisterForChangeEvent. Não avalie a conectividade de rede com base no estado do XUser. Se o XUserState for SignedIn, isso indica que, em algum momento, o usuário foi autenticado nos XBOX services e pode ser tratado como um usuário ativo. No entanto, a rede pode não estar conectada.

​
Adicionar ou remover usuários do jogo

Diferentemente do modelo da ERA do XBOX One, um jogo só pode interagir com os usuários que ele solicitou chamando a função XUserAddAsync. Por exemplo, suponha que dois usuários estejam conectados ao console: o usuário A e o usuário B.
  1. Alguém inicia o jogo. Para este cenário, não importa quem fez isso.
  2. O jogo se registra para alterações de estado do usuário usando XUserRegisterForChangeEvent.
  3. O jogo chama XUserAddAsync e o usuário A entra no jogo.
  4. O jogo agora tem um XUserHandle que representa o usuário A.
  5. No guia, o usuário B opta por sair.
  6. Nenhum evento de alteração de entrada é disparado para o jogo. O jogo nunca soube do usuário B.
  7. No guia, o usuário A opta por sair.
  8. O jogo recebe um evento de alteração que indica primeiro que o usuário A está em processo de saída e, por fim, um evento diferente que indica que o usuário A agora está desconectado.
Embora os jogos possam adicionar usuários, há apenas algumas maneiras de remover usuários, usando um dos métodos a seguir.
  • O jogo pode fechar todos os identificadores que representam o usuário usando a função XUserCloseHandle.
  • O usuário usa o guia para sair do console.
  • O usuário entra em um dispositivo diferente.

​
Tipos de usuários

O XBOX One oferece suporte a dois tipos de usuários: jogadores do XBOX e convidados. Os jogadores do XBOX têm recursos completos como usuários no sistema. Eles são criados inicialmente adicionando uma nova conta no Seletor de Contas, uma interface do usuário fornecida pelo sistema para conectar usuários. Os jogadores do XBOX permanecem no console até serem removidos explicitamente com o aplicativo Configurações. Os convidados do XBOX têm uma única sessão em um console. Eles são criados quando optam, no Seletor de Contas, por jogar como convidado e são patrocinados por outro jogador do XBOX conectado. Os convidados permanecem até saírem, até que o jogador do XBOX patrocinador saia ou até que o console seja desligado. Os jogos que desejam permitir convidados devem especificar a opção AllowGuest ao chamar XUserAddAsync.

​
Padrões para adicionar usuários

Os jogos devem sempre tentar estabelecer um usuário inicial. Há duas maneiras principais de fazer isso.

​
Opção 1: determinar o usuário o mais rápido possível sem mostrar a interface do usuário

  1. Chame XUserAddAsync usando AddDefaultUserSilently. Essa função tenta determinar quem iniciou o jogo sem mostrar nenhuma interface do usuário.
  2. A chamada para XUserAddAsync pode falhar com E\_GAMEUSER\_NO\_DEFAULT\_USER. Se isso acontecer, ninguém estava conectado quando o jogo foi iniciado pela primeira vez. Para estabelecer o usuário inicial, o jogo precisa chamar XUserAddAsync sem usar o sinalizador AddDefaultUserSilently. Diferentemente da opção “silenciosa”, essa chamada garante que todos os problemas de consentimento sejam totalmente resolvidos e que, se a chamada for bem-sucedida, o usuário esteja conectado aos XBOX services. O jogo pode criar um contexto XBOX para esse usuário.

​
Opção 2: determinar o usuário com a possibilidade de mostrar a interface do usuário

Chame XUserAddAsync usando AddDefaultUserAllowingUI. Assim como a opção anterior (com “silenciosa”), essa função tenta determinar quem iniciou o jogo. Diferentemente da opção anterior, se o usuário padrão não puder ser determinado, ela mostra uma interface do usuário para permitir que os jogadores entrem ou se selecionem. Se XUserAddResult for bem-sucedido, o jogo terá um usuário totalmente conectado aos XBOX services e poderá criar um contexto XBOX para esse usuário. Para obter um código de exemplo que demonstra essas etapas, confira Como fazer: prática recomendada para conectar um usuário.

​
Gerenciamento do XUserHandle

Cada XUserHandle representa um usuário. No entanto, é possível que vários desses identificadores representem o mesmo usuário. Os jogos devem usar o seguinte padrão básico.
  1. Manter uma coleção de instâncias de XUserHandle que representam a coleção de usuários com os quais o jogo se importa.
  2. Registrar-se para alterações de estado do XUser chamando XUserRegisterForChangeEvent. Quando você perceber que um usuário está saindo, atualize sua coleção de usuários.
  3. Quando você obtiver um novo XUserHandle de XUserAddAsync, verifique se ele representa um novo usuário. Você pode comparar diretamente com os identificadores usando XUserCompare. Também pode comparar usando a ID local obtida chamando XUserGetLocalId.
  4. Se você tiver várias instâncias de XUserHandle representando o mesmo usuário, use XUserCloseHandle para remover as instâncias extras.
A ID local é um identificador que permanece com o usuário durante todo o tempo de vida desse usuário na sessão de jogo. Use a ID local em todos os processos que um jogo gerar ou se o jogo chamar XLaunchNewGame. No entanto, não use a ID local para identificar um usuário entre sessões de jogo.
Last modified on October 6, 2026