Uso dos privilégios de usuário dos serviços do XBOX no lado do cliente

​

Pré-requisitos

​

Tratamento no lado do cliente e a experiência do jogador para privilégios e upsell

1. O jogador vê uma opção para iniciar uma sessão multiplayer e tenta iniciar uma partida selecionando a opção apropriada na interface.
2. O jogo verifica a “dica” usando a API XUserCheckPrivilege.
   • Se ela estiver presente, presuma que o jogador tem o privilégio e prossiga.
   • Se não estiver, vá para a próxima etapa.
   As APIs dos serviços do XBOX retornam um código de status 403 (HTTP_E_STATUS_FORBIDDEN) quando o acesso a um recurso é negado devido à ausência de um privilégio no XToken. Todos os pontos de extremidade dos serviços do XBOX aplicam o controle de acesso baseado em privilégios conforme apropriado.
3. Em resposta ao código de falha, o jogo chama XUserResolvePrivilegeWithUiAsync com o ID de privilégio apropriado para aquele que você está tentando resolver. Essa função chama os serviços do XBOX para verificar se o jogador tem o privilégio e, em seguida, informa ao jogador por que a ação falhou ou mostra ao jogador a interface para resolver o problema. Os resultados a seguir podem decorrer dessa chamada à API.
   • Mostrar a interface relacionada ao status de aplicação de medidas do jogador emitido pelos moderadores de políticas e aplicação dos serviços do XBOX.
   • Mostrar a interface relacionada aos controles parentais.
   • Promover um serviço de assinatura aplicável, como uma assinatura XBOX Game Pass Essential.
   • Retornar o resultado ao jogo (sucesso ou falha, com um motivo).
   Se os serviços do XBOX ou a rede estiverem inacessíveis, XUserResolvePrivilegeWithUiAsync falhará. Essa falha deve ser tratada como se o jogador não tivesse o privilégio.
4. No retorno de XUserResolvePrivilegeWithUiAsync:
   1. Se for retornada uma falha, o jogo precisa permitir que o jogador continue selecionando o botão, porque (por exemplo) os banimentos do jogador podem expirar ou os controles parentais podem mudar.
   2. Se for retornado sucesso, o problema do jogador foi corrigido, e seu jogo pode tentar a ação novamente. O token do jogador conterá os privilégios necessários como parte da correção executada por XUserResolvePrivilegeWithUiAsync.

​

Código de exemplo

void OnMultiplayerAllowed(XUserHandle userHandle);
void OnMultiplayerDenied(XUserHandle userHandle, HRESULT hr);

// Called when the player selects a multiplayer option.
void CheckMultiplayerPrivilege(XUserHandle userHandle, XTaskQueueHandle queue)
{
    bool hasPrivilege = false;

    // Check the Multiplayer (254) privilege. The deny reason is informational only.
    HRESULT hr = XUserCheckPrivilege(
        userHandle,
        XUserPrivilegeOptions::None,
        XUserPrivilege::Multiplayer,
        &hasPrivilege,
        nullptr);

    if (FAILED(hr) && hr != E_GAMEUSER_RESOLVE_USER_ISSUE_REQUIRED)
    {
        // The check didn't complete. Deny access to multiplayer.
        OnMultiplayerDenied(userHandle, hr);
        return;
    }

    if (SUCCEEDED(hr) && hasPrivilege)
    {
        OnMultiplayerAllowed(userHandle);
        return;
    }

    auto asyncBlock = std::make_unique<XAsyncBlock>();
    ZeroMemory(asyncBlock.get(), sizeof(XAsyncBlock));
    asyncBlock->queue = queue;
    asyncBlock->context = userHandle;

    if (hr == E_GAMEUSER_RESOLVE_USER_ISSUE_REQUIRED)
    {
        // There's an issue with the user that must be resolved before the privilege can be checked.
        asyncBlock->callback = [](XAsyncBlock* async)
        {
            std::unique_ptr<XAsyncBlock> asyncOwner{ async };
            XUserHandle user = static_cast<XUserHandle>(async->context);

            HRESULT hr = XUserResolveIssueWithUiResult(async);
            if (SUCCEEDED(hr))
            {
                // The issue is resolved. Check the privilege again.
                CheckMultiplayerPrivilege(user, async->queue);
            }
            else
            {
                // Deny access. Let the player select the option again later.
                OnMultiplayerDenied(user, hr);
            }
        };

        hr = XUserResolveIssueWithUiAsync(userHandle, nullptr, asyncBlock.get());
    }
    else
    {
        // The check succeeded, but the player doesn't have the privilege.
        asyncBlock->callback = [](XAsyncBlock* async)
        {
            std::unique_ptr<XAsyncBlock> asyncOwner{ async };
            XUserHandle user = static_cast<XUserHandle>(async->context);

            HRESULT hr = XUserResolvePrivilegeWithUiResult(async);
            if (SUCCEEDED(hr))
            {
                // The player now has the privilege. It isn't necessary to call XUserCheckPrivilege again.
                OnMultiplayerAllowed(user);
            }
            else
            {
                // Deny access. Let the player select the option again later.
                OnMultiplayerDenied(user, hr);
            }
        };

        hr = XUserResolvePrivilegeWithUiAsync(
            userHandle,
            XUserPrivilegeOptions::None,
            XUserPrivilege::Multiplayer,
            asyncBlock.get());
    }

    if (SUCCEEDED(hr))
    {
        // The UI started. The completion callback owns the XAsyncBlock and reports the outcome.
        // Success here doesn't mean that the player has the privilege.
        asyncBlock.release();
    }
    else
    {
        // The UI didn't start. Deny access to multiplayer.
        OnMultiplayerDenied(userHandle, hr);
    }
}

​

Práticas recomendadas para o tratamento de privilégios no lado do aplicativo

​

Frequência de resolução de privilégios no aplicativo

• Para aplicativos de streaming de mídia, como players de vídeo, resolva as verificações de privilégio uma vez a cada seleção do botão Play (início do stream) ou no início de uma playlist (para vários streams, como uma playlist de música).
• Para aplicativos de mensagens, verifique os privilégios uma vez, na primeira mensagem enviada.
• Para jogos multiplayer que usam serviços de partida de terceiros, resolva as verificações de privilégio no início de cada sessão (partida).

​

Nunca presuma o nível de assinatura de um usuário

​

Modo offline

​

Direcionando ao jogador correto

​

Verificando sem interface ou com a interface fora de foco

​

Testando o controle de acesso baseado em privilégios nos seus jogos

• Direitos de assinatura efetivos do jogador
• Direitos de privilégio efetivos do dispositivo
• Direitos de privilégio efetivos da plataforma cliente
• Direitos de privilégio efetivos do jogo atual
  • É possível empacotar um jogo com um conjunto de privilégios para que todos os jogadores do jogo recebam automaticamente esses privilégios para uso no jogo em execução. Se o seu jogo exigir esse recurso, entre em contato com seu gerente de conta da Microsoft.
• Controles parentais, para que os pais decidam quais privilégios adicionar ou remover para as crianças da família
• Os moderadores do XBOX podem banir privilégios de jogadores ou dispositivos identificados como abusivos com o serviço

​

Gerenciando e verificando os privilégios e as permissões dos jogadores

• No PC: acesse https://aka.ms/XboxPrivSettings.
• No XBOX: acesse Configurações -> Geral -> Segurança online e família -> Privacidade e segurança online -> Privacidade do XBOX

​

Privilégios verificados com XUserCheckPrivilege

XUserPrivilege::CrossPlay

• Descrição: permite que um jogador participe de uma sessão de jogo com outros jogadores reais que não estão conectados aos serviços do XBOX em cenários como: jogo síncrono jogador contra jogador na mesma sessão, jogo assíncrono baseado em turnos, jogo em equipe, matchmaking iniciado pelo usuário, envio ou aceitação de convites e sessões com entrada em andamento.
• Requisito: XR-045 - XBOX services and Account Privileges
• ID do privilégio: 185
• Configuração no PC: Você pode jogar com pessoas fora dos serviços do XBOX
• Configuração no XBOX: Você pode participar de jogos entre redes

XUserPrivilege::Sessions

• Descrição: permite que um jogador participe de experiências conectadas para um jogador em ambientes compartilhados ou em cenários em que um título é híbrido, com partes gratuitas e multiplayer pago, e usa esse privilégio para controlar essas experiências nos consoles XBOX. As experiências para um jogador não podem ter nenhum recurso coberto pelos privilégios 252 ou 254 (Comunicação e Multiplayer, respectivamente). O uso deste privilégio é uma funcionalidade de título que exige a aprovação da plataforma.
• Requisito: XR-045 - XBOX services and Account Privileges
• ID do privilégio: 189
• Configuração no PC: Você pode participar de jogos multiplayer
• Configuração no XBOX: Você pode participar de jogos multiplayer

XUserPrivilege::Multiplayer

• Descrição: permite que um jogador participe de sessões de jogo multiplayer online com usuários reais (não bots) em cenários como: jogo síncrono jogador contra jogador na mesma sessão, jogo assíncrono baseado em turnos, jogo em equipe, matchmaking iniciado pelo usuário, envio ou aceitação de convites e sessões com entrada em andamento. Observe que esse privilégio não se aplica a jogos multiplayer locais executados no mesmo dispositivo.
• Requisito: XR-045 - XBOX services and Account Privileges
• ID do privilégio: 254
• Configuração no PC: Você pode participar de jogos multiplayer
• Configuração no XBOX: Você pode participar de jogos multiplayer

XUserPrivilege::UserGeneratedContent

• Descrição: permite que um jogador veja o UGC de outros usuários online, baixe o UGC de outros usuários ou compartilhe o próprio UGC online. Isso não restringe o uso de UGC baixado anteriormente.
• Requisito: XR-045 - XBOX services and Account Privileges
• ID do privilégio: 247
• Configuração no PC: Você pode ver e carregar criações da comunidade
• Configuração no XBOX: Você pode ver e carregar criações da comunidade

XUserPrivilege::SocialNetworkSharing

• Descrição: somente consoles XBOX: permite que um jogador compartilhe informações, incluindo o progresso no jogo, conteúdo gerado pelo Kinect, clipes de jogo e assim por diante, fora da rede XBOX.
• Requisito: XR-045 - XBOX services and Account Privileges
• ID do privilégio: 220
• Configuração no XBOX: Você pode compartilhar fora do XBOX

XUserPrivilege::Communications

• Descrição: permite que um jogador se comunique com quaisquer outros usuários dos serviços do XBOX por voz ou texto.
• Requisito: XR-045 - XBOX services and Account Privileges
• ID do privilégio: 252
• Configuração no PC: Outras pessoas podem se comunicar por voz, texto ou convites
• Configuração no XBOX: Outras pessoas podem se comunicar por voz, texto ou convites

​

Permissões verificadas com XblPrivacyCheckPermissionAsync

XblPermission::CommunicateUsingText

• Descrição: verifica se o jogador pode ou não enviar uma mensagem com conteúdo de texto ao usuário de destino. Esse valor não muda se o jogador tiver silenciado o usuário de destino; nesse caso, use CommunicateUsingVoice. Esse valor será false se, por exemplo, você tiver definido suas comunicações apenas para amigos e o destino não for um amigo. Esse valor será false se, por exemplo, o jogador de destino tiver bloqueado você. Esse valor será false se, por exemplo, você tiver definido suas configurações de comunicação como Bloqueado.
• Requisito: XR-015 - Managing Player Communication
  • Ao verificar outro usuário dos serviços do XBOX
    • Configuração no PC: Outras pessoas podem se comunicar por voz, texto ou convites
    • Configuração no XBOX: Outras pessoas podem se comunicar por voz, texto ou convites
  • Ao verificar um usuário anônimo
    • Configuração no PC: Você pode se comunicar fora dos serviços do XBOX por voz e texto
    • Configuração no XBOX: Você pode se comunicar fora do XBOX por voz e texto

XblPermission::CommunicateUsingVoice

• Descrição: verifica se o jogador pode ou não se comunicar por voz com o usuário de destino. Será false se o jogador tiver silenciado o usuário de destino.
• Requisito: XR-015 - Managing Player Communication
  • Ao verificar outro usuário dos serviços do XBOX
    • Configuração no PC: Outras pessoas podem se comunicar por voz, texto ou convites
    • Configuração no XBOX: Outras pessoas podem se comunicar por voz, texto ou convites
  • Ao verificar um usuário anônimo
    • Configuração no PC: Você pode se comunicar fora dos serviços do XBOX por voz e texto
    • Configuração no XBOX: Você pode se comunicar fora do XBOX por voz e texto

​

Testando os privilégios fornecidos por assinaturas

​

Testando os privilégios fornecidos pelo jogo em execução

​

Testando os privilégios removidos pelo controle parental

​

IDs de privilégio a verificar

​

Lógica de cálculo dos privilégios

​

Direitos de privilégio resultantes do tipo de dispositivo

​

Direitos de privilégio efetivos resultantes de assinaturas

• O jogador comprou o produto de assinatura.
• Outro jogador ativo no mesmo dispositivo comprou o produto de assinatura.
• O produto de assinatura está associado ao dispositivo que o jogador está usando no momento.

​

Direitos promocionais

​

Privilégios removidos de contas de convidado patrocinado

​

Segurança online e aplicação de medidas pela Microsoft

​

Controles parentais

​

Privilégios para assinantes do XBOX Game Pass Essential

​

Assinaturas de parceiros e privilégios

​

Títulos free-to-play e privilégios de multiplayer

​

Títulos híbridos e privilégios de multiplayer

​

Confira também