> ## 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.

# Identidade do usuário e XUser

> Identidade do usuário e XUser

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<br />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<a id="pattern_for_adding" />

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](/pt-BR/build/core-features/common/user/xuser_howto_best_practice_signing_in).

## 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.


## Related topics

- [Identidad de usuario y XUser](/es/build/core-features/common/user/player-identity-xuser.md)
- [Identidad de usuario y API de XUser en el GDK](/es/build/core-features/common/user/index.md)
- [Glossário de termos e siglas do GDK](/pt-BR/home/glossary.md)
- [XR-112 Estabelecimento de um usuário e um controle durante a ativação inicial e a retomada](/pt-BR/publishing/certification/xr/xr-112.md)
- [Portar do Steam](/pt-BR/paths/porting/from-steam.md)