Suporte multiplataforma do XUser

​

Visão geral

​

Requisitos de integração

​

Consoles XBOX e Microsoft Store / Game Pass no Windows

​

Outras lojas no Windows

• Os jogos usam os serviços e a interface do usuário internos do sistema operacional.
• O instalador deve executar o GamingRepair.exe para garantir que o Gaming Runtime Service esteja instalado.

1. Inclua a ferramenta no pacote do jogo – Ela está incluída no GDK em [GDK]\bin\GamingRepair.exe.
2. Adicione uma ação personalizada – Execute a ferramenta antes da instalação do jogo (por exemplo: start /wait “Installing Gaming Services” GamingRepair.exe scenarioExternal). Isso verifica, baixa, instala ou repara quaisquer componentes ausentes do Gaming Runtime.
3. Trate erros – Verifique o código de saída da ferramenta. Se ela falhar, notifique o usuário e forneça instruções de instalação manual.

​

Diferenças entre plataformas e API unificada

• Em plataformas com suporte nativo (XBOX, Windows) - O XUser usa os serviços internos do sistema operacional para autenticação, interface do usuário e armazenamento de credenciais. Os jogos chamam as APIs do XUser e o sistema lida com os detalhes automaticamente.
• Em plataformas sem suporte nativo (Steam Deck etc.) - O XUser expõe as mesmas APIs principais, mas os jogos devem implementar manipuladores de eventos para fornecer a interface do usuário necessária (como exibir códigos QR para entrada) e o armazenamento de dados. Isso dá aos jogos controle total sobre a experiência de autenticação.

​

Novas funcionalidades multiplataforma

​

Autenticação Remote Connect

​

Imposição de sessão única (SPoP)

​

Remote Connect para entrada entre dispositivos

​

Como funciona

​

O fluxo

1. Registro do manipulador de eventos - O jogo registra um manipulador de eventos do Remote Connect antes de iniciar a entrada usando XUserPlatformRemoteConnectSetEventHandlers(...). O título fornece retornos de chamada para tratar dois eventos principais:
   • Evento Show - Disparado quando o XUser precisa que o jogo exiba o código de uso único ou o código QR. O manipulador apresenta uma caixa de diálogo ou sobreposição com o código e as instruções (por exemplo: “Escaneie este código QR ou acesse xbox.com/play e insira o código ABCD para entrar”).
   • Evento Close - Disparado quando o processo de entrada remota é concluído ou cancelado, sinalizando ao jogo para ocultar ou fechar a caixa de diálogo do código.
2. Início da entrada do usuário - Ao chamar XUserAddAsync para adicionar um novo usuário, se nenhum usuário local já estiver conectado, o sistema XUser poderá usar o fluxo do Remote Connect (especialmente em plataformas sem interface ou de terceiros).
3. Exibição do código - O XUser invoca o retorno de chamada “show”, fornecendo o código de autenticação ou a URL. O manipulador de interface do usuário do jogo (como OnRemoteConnectShow) exibe o código QR ou a cadeia de caracteres do código ao usuário.
4. Autenticação do usuário - O jogador usa o telefone ou navegador da Web para entrar com o código fornecido, vinculando a conta do XBOX à sessão atual.
5. Conclusão - Depois que a autenticação é concluída no back-end, o XUser invoca o retorno de chamada “close”, sinalizando que o código pode ser removido da tela. Nesse ponto, o XUser obteve o token do XBOX Live do usuário e cria o XUserHandle.
6. Sucesso - A tarefa XUserAddAsync retorna com êxito e o usuário é conectado sem inserir credenciais diretamente no dispositivo.

​

Implementação

XUserPlatformRemoteConnectEventHandlers remoteConnect = {};
remoteConnect.context = nullptr;
remoteConnect.show = &OnRemoteConnectShow;   // Display QR/code dialog
remoteConnect.close = &OnRemoteConnectClose; // Dismiss dialog

HRESULT hr = XUserPlatformRemoteConnectSetEventHandlers(nullptr, &remoteConnect);

​

Considerações sobre a experiência do usuário

• Instruções claras - Explique claramente o que o usuário precisa fazer ao exibir o código.
• Tratamento de erros - Se o usuário cancelar no lado remoto ou ocorrer um erro, o XUser fará a tentativa de entrada falhar. Trate isso no retorno de chamada de conclusão normal de XUserAddAsync.
• Descarte oportuno - Oculte o código imediatamente quando o evento de fechamento ocorrer para evitar confusão do usuário.
• Design visual - Garanta que o código QR e as instruções sejam grandes o suficiente e claramente visíveis no dispositivo de destino.

​

Imposição de sessão única (SPoP)

​

Como funciona

​

O fluxo

1. Registro do manipulador de eventos - O jogo registra um manipulador de eventos de prompt SPoP antes de iniciar a entrada usando XUserPlatformSpopPromptSetEventHandlers(...).
2. Detecção de conflito - Ao chamar XUserAddAsync para adicionar um usuário, se o XUser detectar que o mesmo usuário já está ativo em outro lugar no mesmo título, ele invocará o manipulador SPoP.
3. Exibição do prompt - O manipulador do jogo recebe o gamertag moderno do usuário e um identificador de operação. O manipulador deve exibir um prompt de interface do usuário como: “[Gamertag] já está jogando em outro dispositivo. Deseja jogar aqui (o que desconectará a sessão no outro lugar) ou trocar para uma conta diferente?” com opções como “Jogar aqui” e “Trocar de conta”.
4. Escolha do usuário - O jogo aguarda o usuário fazer uma seleção. A operação permanece pendente até que o jogo chame a API de conclusão.
5. Conclusão da operação - Com base na escolha do usuário, o jogo chama XUserPlatformSpopPromptComplete com o resultado apropriado:
   • Jogar aqui - XUserPlatformSpopOperationResult::SignInHere - Conecta neste dispositivo e encerra a sessão remota.
   • Trocar de conta - XUserPlatformSpopOperationResult::SwitchAccount - Cancela a entrada neste dispositivo, permitindo que o usuário escolha uma conta diferente.
   • Cancelar - XUserPlatformSpopOperationResult::Canceled - Anula a tentativa de entrada.
6. Resolução - O XUser prossegue com base no resultado. Se “Jogar aqui” for escolhido, a sessão remota será encerrada (o outro dispositivo receberá um evento de saída) e o usuário se tornará ativo localmente. Se “Trocar de conta” for escolhido, XUserAddAsync falhará e o jogo poderá solicitar uma conta diferente.

​

Implementação

HRESULT hr = XUserPlatformSpopPromptSetEventHandlers(nullptr, &OnSpopPrompt, nullptr);

// If user chose "Play here"
XUserPlatformSpopPromptComplete(operation, XUserPlatformSpopOperationResult::SignInHere);

// If user chose "Switch account"
XUserPlatformSpopPromptComplete(operation, XUserPlatformSpopOperationResult::SwitchAccount);

// If dialog was canceled
XUserPlatformSpopPromptComplete(operation, XUserPlatformSpopOperationResult::Canceled);

​

Considerações sobre a experiência do usuário

• Mensagens claras - Exiba o gamertag do usuário e explique claramente que continuar o desconectará do outro dispositivo.
• Opções visíveis - Torne as opções “Jogar aqui” e “Trocar de conta” claramente visíveis e compreensíveis.
• Evite conflitos de salvamento - Enfatize que isso evita conflitos de jogos salvos e problemas de jogabilidade simultânea.
• Comportamento específico da plataforma - No XBOX e no Windows, o sistema operacional lida com isso automaticamente e o manipulador SPoP nunca será invocado. Em outras plataformas, seu jogo é responsável por apresentar essa escolha.

​

Confira também