Visão geral da XBOX Live Helper library

A XBOX Live Helper library para o PlayFab Party foi projetada para ajudar os jogos que usam o PlayFab Party a atender às políticas do XBOX Live relacionadas à comunicação (XR-015 e XR-045). A XBOX Live Helper library está disponível no Nuget.org.

Compatibilidade com a biblioteca do PlayFab Party

Embora nos esforcemos para minimizar alterações significativas em nossas APIs, algumas alterações feitas na API do PlayFab Party podem fazer com que a XBOX Live Helper library retorne valores incorretos. Consulte a tabela abaixo para garantir que as versões das suas bibliotecas sejam compatíveis.

Versão da XBOX Live Helper Library	Versão do PlayFab Party 1.0.1	Versão do PlayFab Party 1.3.0+
1.0.1	✔
1.1.0	✔
1.2.0		✔
1.2.5		✔

Acompanhando os usuários do XBOX Live

A PlayFab Party XBOX Live Helper library deve ser informada explicitamente sobre os usuários do XBOX Live que estão participando no momento da sessão do Party. É recomendável que os títulos informem a biblioteca escutando as alterações no seu documento de sessão multijogador e refletindo essa lista na XBOX Live Helper library por meio de PartyXblManager::CreateLocalChatUser e PartyXblManager::CreateRemoteChatUser. Para usuários locais:

void
OnLocalXboxUserAddedToMPSD(
    uint64_t xboxUserId
    )
{
    PartyXblLocalChatUser* localChatUser;
    PartyError err = PartyXblManager::GetSingleton().CreateLocalChatUser(xboxUserId, nullptr, &localChatUser);
    if (PARTY_FAILED(err))
    {
        DEBUGLOG("CreateLocalChatUser failed: %s\n", PartyXblManager::GetErrorMessage(err));
        return;
    }
}

Nesse ponto, se já existir um PartyLocalChatControl para o usuário local do XBOX correspondente, você poderá associá-lo a esse PartyXblLocalChatUser por meio dos métodos SetCustomContext.

    localChatControl->SetCustomContext(localChatUser);
    localChatUser->SetCustomContext(localChatControl);

Caso contrário, você poderá usar esse novo PartyXblLocalChatUser para gerar o controle de chat e associá-los nesse momento. Confira Criando PartyLocalChatControls a partir de PartyXblLocalChatUsers para obter mais informações. Para usuários remotos:

void
OnRemoteXboxUserAddedToMPSD(
    uint64_t xboxUserId
    )
{
    PartyXblChatUser* remoteChatUser;
    PartyError err = PartyXblManager::GetSingleton().CreateRemoteChatUser(remoteXboxUserId, &remoteChatUser);
    if (PARTY_FAILED(err))
    {
        DEBUGLOG("CreateRemoteChatUser failed: %s\n", PartyXblManager::GetErrorMessage(err));
        return;
    }

Nesse ponto, se já existir um PartyChatControl para o usuário remoto do XBOX correspondente, você poderá associá-lo a esse PartyXblChatUser por meio dos métodos SetCustomContext.

    remoteChatControl->SetCustomContext(remoteChatUser);
    remoteChatUser->SetCustomContext(remoteChatControl);

Lembre-se de que as atualizações do documento de sessão e as atualizações da lista de controles de chat remotos podem não estar ordenadas, e você pode precisar de uma lógica de associação semelhante ao processar atualizações de PartyChatControlCreatedStateChange para controles de chat remotos. Para usuários de chat locais e remotos, é importante lembrar que a biblioteca principal do Party identifica usuários e controles de chat por meio de IDs de entidade do PlayFab, enquanto a biblioteca auxiliar do XBOX Live identifica os usuários de chat com IDs de usuário do XBOX. Portanto, muitas vezes é necessário converter entre os dois. Consulte Mapeamento entre IDs de usuário do XBOX Live e IDs de entidade do PlayFab para obter mais informações.

Criando PartyLocalChatControls a partir de PartyXblLocalChatUsers

Os objetos PartyXblLocalChatUser geralmente só são úteis quando associados a objetos PartyLocalUser e PartyLocalChatControl na biblioteca do Party. Gerar objetos PartyLocalUser e PartyLocalChatControl exige que os títulos façam login dos seus usuários no PlayFab e recuperem o entityId e o titlePlayerEntityToken do usuário. O login pode ser feito por meio do PlayFab CPP SDK, mas, se um título pretende usar credenciais do XBOX Live para fazer login no PlayFab, pode usar PartyXblManager::LoginToPlayFab para evitar adicionar uma dependência extra. O exemplo a seguir mostra como a XBOX Live Helper library pode ajudar você a criar objetos PartyLocalUser e PartyLocalChatControl a partir de objetos PartyXblLocalChatUser. Para obter mais informações sobre como criar objetos PartyXblLocalChatUser, confira Acompanhando os usuários do XBOX Live.

    err = PartyXblManager::GetSingleton().LoginToPlayFab(localChatUser, nullptr);
    if (PARTY_FAILED(err))
    {
        DEBUGLOG("LoginToPlayFab failed: %s\n", PartyXblManager::GetErrorMessage(err));
        return;
    }

Pouco depois de chamar PartyXblManager::LoginToPlayFab, você receberá um PartyXblLoginToPlayFabCompletedStateChange contendo o resultado da operação de login.

    PartyLocalUser* partyLocalUser;
    if (stateChange->stateChangeType == PartyXblStateChangeType::LoginToPlayFabCompleted)
    {
        auto loginToPlayFabCompleted = static_cast<PartyXblLoginToPlayFabCompletedStateChange*>(stateChange);
        if (loginToPlayFabCompleted->result == PartyXblStateChangeResult::Succeeded)
        {
            err = PartyManager::GetSingleton().CreateLocalUser(
                loginToPlayFabCompleted->entityId,
                loginToPlayFabCompleted->titlePlayerEntityToken,
                partyLocalUser));
            if (PARTY_FAILED(err))
            {
                DEBUGLOG("CreateLocalUser failed: %s\n", PartyManager::GetErrorMessage(err));
                return;
            }
        }
    }

    PartyLocalDevice* localDevice;
    err = PartyManager::GetSingleton().GetLocalDevice(&localDevice);
    if (PARTY_FAILED(err))
    {
        DEBUGLOG("GetLocalDevice failed: %s\n", PartyManager::GetErrorMessage(err));
        return;
    }

    PartyLocalChatControl* localChatControl;
    err = localDevice->CreateChatControl(partyLocalUser, nullptr, nullptr, &localChatControl);
    if (PARTY_FAILED(err))
    {
        DEBUGLOG("CreateChatControl failed: %s\n", PartyManager::GetErrorMessage(err));
        return;
    }

    // We can use the custom context on the PartyXblLocalChatUser to store the PartyLocalChatControl for easy access
    // in the future.
    localChatUser->SetCustomContext(localChatControl);

Respeitando as preferências de acessibilidade de um usuário do XBOX Live

O objeto PartyXblLocalChatUser expõe algumas das preferências de acessibilidade do usuário do XBOX Live que são relevantes para as sessões de chat do Party. Os títulos podem usar essas informações para oferecer uma experiência melhor aos jogadores, habilitando imediatamente alguns dos recursos de acessibilidade do Party.

    PartyXblAccessibilitySettings accessibilitySettings;
    err = localChatUser->GetAccessibilitySettings(&accessibilitySettings);
    if (PARTY_FAILED(err))
    {
        DEBUGLOG("GetAccessibilitySettings failed: %s\n", PartyXblManager::GetErrorMessage(err));
        return;
    }

    if (accessibilitySettings.speechToTextEnabled)
    {
        PartyVoiceChatTranscriptionOptions option = PartyVoiceChatTranscriptionOptions::TranscribeOtherChatControlsWithMatchingLanguages;
        m_localChatControl->SetTranscriptionOptions(option, nullptr);
    }

Respeitando as configurações de privacidade e as permissões de um usuário do XBOX Live

De acordo com as políticas do XBOX Live, os títulos não devem permitir a comunicação pelo XBOX Live quando a privacidade ou as permissões do usuário não a permitirem. A XBOX Live Helper library ajuda você a fazer isso, permitindo consultar as PartyChatPermissionOptions mais restritivas entre dois usuários permitidas pelas políticas do XBOX Live. Sempre que esse valor mudar, um PartyXblRequiredChatPermissionInfoChangedStateChange será gerado pela biblioteca. As PartyChatPermissionOptions atualizadas podem ser obtidas por meio de uma chamada a PartyXblLocalChatUser::GetRequiredChatPermissionInfo().

    PartyXblChatUser* remoteChatUser;
    PartyError err = PartyXblManager::GetSingleton().CreateRemoteChatUser(remoteXboxUserId, &remoteChatUser);
    if (PARTY_FAILED(err))
    {
        DEBUGLOG("CreateRemoteChatUser failed: %s\n", PartyXblManager::GetErrorMessage(err));
        return;
    }

    // Once the chat control representing this remote Xbox Live user joins a network, we can use the custom context
    // on the PartyXblChatUser to store the chat control object for quick access in the future.
    remoteChatUser->SetCustomContext(m_remotePartyChatControl);

A biblioteca auxiliar do XBOX Live acompanha as configurações de privacidade e de privilégios de cada usuário de chat remoto em relação a cada usuário de chat local, comunicando-se com os serviços de privacidade do XBOX Live. Além disso, a biblioteca escutará as alterações nessas configurações assinando as atualizações de Atividade em Tempo Real. Quando novos usuários de chat remotos forem adicionados ou quando a relação de privacidade e de privilégios entre um usuário de chat local e um usuário de chat remoto existente mudar, um PartyXblRequiredChatPermissionInfoChangedStateChange será gerado para notificar você de que um valor atualizado de PartyChatPermissionOptions está disponível.

    // Wait for PartyXblRequiredChatPermissionInfoChangedStateChange
    if (stateChange->stateChangeType == PartyXblStateChangeType::RequiredChatPermissionInfoChanged)
    {
        auto chatPermissionChanged = static_cast<PartyXblRequiredChatPermissionInfoChangedStateChange*>(stateChange);

        PartyXblLocalChatUser* localChatUser = chatPermissionChanged->localChatUser;
        PartyXblChatUser* targetChatUser = chatPermissionChanged->targetChatUser;

        PartyXblChatPermissionInfo chatPermissionInfo;
        PartyError err = localChatUser->GetRequiredChatPermissionInfo(targetChatUser, &chatPermissionInfo);
        if (PARTY_FAILED(err))
        {
            DEBUGLOG("GetRequiredChatPermissionInfo failed: %s\n", PartyXblManager::GetErrorMessage(err));
            return;
        }

        PartyLocalChatControl* localChatControl;
        localChatUser->GetCustomContext(reinterpret_cast<void**>(&localChatControl));
        if (PARTY_FAILED(err))
        {
            DEBUGLOG("GetCustomContext failed: %s\n", PartyXblManager::GetErrorMessage(err));
            return;
        }

        PartyChatControl* targetChatControl;
        targetChatUser->GetCustomContext(reinterpret_cast<void**>(&targetChatControl));
        if (PARTY_FAILED(err))
        {
            DEBUGLOG("GetCustomContext failed: %s\n", PartyXblManager::GetErrorMessage(err));
            return;
        }

        localChatControl->SetPermission(targetChatControl, chatPermissionInfo.chatPermissionMask);
        if (PARTY_FAILED(err))
        {
            DEBUGLOG("SetPermission failed: %s\n", PartyXblManager::GetErrorMessage(err));
            return;
        }
    }

A estrutura PartyXblChatPermissionInfo contém duas informações:

Uma máscara PartyChatPermissionOptions, que pode ser passada como está para PartyLocalChatControl::SetPermission() ou usada como máscara binária se você já tiver um valor de PartyChatPermissionOptions que gostaria de usar, mas quiser garantir que está respeitando as políticas do XBOX Live.
Um valor PartyXblChatPermissionMaskReason, que fornece informações adicionais sobre o valor de PartyXblChatPermissionInfo::chatPermissionMask

PartyXblChatPermissionMaskReason	Explicação
NoRestriction	No momento, não há nenhuma restrição aplicada a esta permissão de chat.
Determining	A comunicação é restrita enquanto o privilégio de comunicação e as configurações de privacidade do usuário local estão sendo determinados
Privilege	A comunicação é restrita devido ao privilégio de comunicação do usuário local.
Privacy	A comunicação é restrita devido às configurações de privacidade do usuário local em relação ao usuário de chat de destino.
InvalidTargetUser	A comunicação é restrita porque o usuário de destino não foi reconhecido como válido pelos serviços do XBOX Live.
XboxLiveServiceError	Não foi possível determinar com êxito a permissão de chat necessária devido a problemas com os serviços do XBOX Live.
UnknownError	Não foi possível determinar com êxito a permissão de chat necessária devido a um erro interno desconhecido.

Respeitando as permissões de comunicação entre redes

Os títulos que dão suporte ao jogo e à comunicação entre redes, entre jogadores do XBOX Live e jogadores que não são do XBOX Live, precisam verificar as permissões de comunicação antes de permitir a comunicação entre esses jogadores. A XBOX Live Helper library fornece essas informações por meio de PartyXblLocalChatUser::GetCrossNetworkCommunicationPrivacySetting(). Esse método retorna uma enumeração PartyXblCrossNetworkCommunicationPrivacySetting com três valores possíveis:

PartyXblCrossNetworkCommunicationPrivacySetting	Explicação
Allowed	As permissões deste usuário do XBOX Live estão definidas para permitir a comunicação com todos os jogadores de outras redes.
FriendsOnly	As permissões deste usuário do XBOX Live estão definidas para permitir a comunicação apenas com amigos de outras redes.
Disallowed	As permissões deste usuário do XBOX Live não permitem nenhuma comunicação com jogadores de outras redes.

    PartyXblCrossNetworkCommunicationPrivacySetting crossNetworkSetting;
    localChatUser->GetCrossNetworkCommunicationPrivacySetting(&crossNetworkSetting);

    if (crossNetworkSetting == PartyXblCrossNetworkCommunicationPrivacySetting::Disallowed)
    {
        m_localChatControl->SetPermissions(crossNetworkChatControl, PartyChatPermissionOptions::None);
    }

Mais informações sobre o XR-015 e como ele se aplica ao jogo e à comunicação entre redes podem ser encontradas aqui

Mapeamento entre IDs de usuário do XBOX Live e IDs de entidade do PlayFab

Muitos títulos do XBOX Live que usam o PlayFab Party precisam converter entre IDs de usuário do XBOX Live (usadas em todo o ecossistema do XBOX Live) e IDs de entidade do PlayFab (usadas pelo PlayFab Party). Usando PartyXblManager::GetEntityIdsFromXboxLiveUserIds, os títulos podem recuperar uma lista de IDs de entidade do PlayFab correspondentes a uma determinada lista de IDs de usuário do XBOX Live. Espera-se que os títulos já tenham uma lista de IDs de usuário do XBOX Live por meio do uso de um serviço externo de lista de participantes, como o Multiplayer Session Directory. Ao associar as IDs de usuário do XBOX Live da lista de participantes às respectivas IDs de entidade do PlayFab, podemos construir um mapeamento de todas as IDs de entidade do PlayFab correspondentes à lista de participantes da sua sessão de jogo. Esse mapeamento pode então ser usado para associar objetos PartyEndpoint e PartyChatControl aos usuários do XBOX Live correspondentes.

Cada ID de usuário do XBOX Live só será mapeada para uma ID de entidade do PlayFab se esse usuário do XBOX Live já tiver sido vinculado a uma conta do PlayFab. Uma conta do PlayFab é criada e vinculada automaticamente na primeira vez que PartyXblManager::LoginToPlayFab é chamado para um determinado usuário do XBOX. Como alternativa, os consumidores do PlayFab SDK podem usar a API LoginWithXbox para obter os mesmos resultados.

O PartyXblLocalChatUser local será usado para a autenticação no PlayFab. Se o usuário não tiver feito login anteriormente no PlayFab com uma chamada a PartyXblManager::LoginToPlayFab, a XBOX Live Helper library precisará autenticar o usuário em segundo plano.

    uint32_t userCount;
    PartyXblChatUserArray chatUsers;
    PartyError err = PartyXblManager::GetSingleton().GetChatUsers(&userCount, &users);
    if (PARTY_FAILED(err))
    {
        DEBUGLOG("GetChatUsers failed: %s\n", PartyXblManager::GetErrorMessage(err));
        return;
    }

    // The list of remote Xbox Live User IDs. This can be populated with arbitrary IDs
    // std::vector<uint64_t> remoteXboxLiveUserIds = {2533274792693551, 2814659110958830};
    //
    // but can also be pulled from the list of remote chat users
    std::vector<uint64_t> remoteXboxLiveUserIds;
    for (uint32_t i = 0; i < userCount; ++i)
    {
        PartyXblChatUser* chatUser = users[i];

        PartyXblLocalChatUser* localChatUser;
        err = chatUser->GetLocal(&localChatUser);
        if (PARTY_FAILED(err))
        {
            DEBUGLOG("PartyChatUser(0x%p)::GetLocal failed: %s\n", chatUser, PartyXblManager::GetErrorMessage(err));
            return;
        }

        if (localChatUser != nullptr)
        {
            continue; // ignore local users
        }

        uint64_t userId;
        err = chatUser->GetXboxUserId(&userId);
        if (PARTY_FAILED(err))
        {
            DEBUGLOG("PartyChatUser(0x%p)::GetXboxUserId failed: %s\n", chatUser, PartyXblManager::GetErrorMessage(err));
            return;
        }

        remoteXboxLiveUserIds.push_back(userId);
    }

    err = PartyXblManager::GetSingleton().GetEntityIdsFromXboxLiveUserIds(
        remoteXboxLiveUserIds.size(),
        remoteXboxLiveUserIds.data(),
        localChatUser,
        nullptr);
    if (PARTY_FAILED(err))
    {
        DEBUGLOG("GetEntityIdsFromXboxLiveUserIds failed: %s\n", PartyXblManager::GetErrorMessage(err));
        return;
    }

Pouco depois de chamar PartyXblManager::GetEntityIdsFromXboxLiveUserIds, você receberá um PartyXblGetEntityIdsFromXboxLiveUserIdsCompletedStateChange contendo o resultado da operação. Esse resultado pode ser usado para construir ou atualizar seus mapeamentos.

    // Wait for PartyXblGetEntityIdsFromXboxLiveUserIdsCompletedStateChange
    if (stateChange->stateChangeType == PartyXblStateChangeType::GetEntityIdsFromXboxLiveUserIdsCompleted)
    {
        std::vector<std::pair<uint64_t, std::string>> cachedXboxUserIdToPlayFabEntityIdMap;

        auto getEntityIdsFromXboxLiveUserIdsResult = static_cast<PartyXblGetEntityIdsFromXboxLiveUserIdsCompletedStateChange*>(stateChange);
        for (uint32_t i = 0; i < getEntityIdsFromXboxLiveUserIdsResult.entityIdMappingCount; ++i)
        {
            const PartyXblXboxUserIdToPlayFabEntityIdMapping& idMapping = getEntityIdsFromXboxLiveUserIdsResult.entityIdMappings[i];

            Log("   Xbox Live User ID: %llu", idMapping.xboxLiveUserId);
            if (strlen(idMapping.playfabEntityId)) != 0)
            {
                Log("    PlayFab Entity ID: %s", idMapping.playfabEntityId);
                cachedXboxUserIdToPlayFabEntityIdMap.emplace_back(idMapping.xboxLiveUserId, idMapping.playfabEntityId);
            }
            else
            {
                // This Xbox Live User did not have a linked PlayFab Account.
                Log("    PlayFab Entity ID: NOT FOUND");
            }
        }

        m_cachedXboxUserIdToPlayFabEntityIdMap = std::move(cachedXboxUserIdToPlayFabEntityIdMap);

Com esse mapeamento, os títulos podem reconhecer quando um objeto do Party representa um usuário do XBOX Live.

uint64_t
GetXboxUserIdFromPlayFabEntityId(
    PartyString entityId
    )
{
    for (const std::pair<uint64_t, std::string>& idMapping : m_cachedXboxUserIdToPlayFabEntityIdMap)
    {
        const std::string& entityIdForXboxUserId = idMapping.second;
        if (entityIdForXboxUserId == entityId)
        {
            return idMapping.first;
        }
    }

    // Failed to find a matching Xbox User ID. This Entity ID does not represent an Xbox Live user.
    return 0;
}

Considerações especiais para o Windows

No Windows, a XBOX Live Helper library precisa da ajuda do título para obter os tokens do XBOX Live. A biblioteca solicitará tokens gerando PartyXblTokenAndSignatureRequestedStateChange. O título pode usar a XBOX Authentication Library (XAL) para atender a essas solicitações. Transferir esse trabalho para o título garante que ele mantenha controle total sobre qualquer tratamento de interface do usuário e solicitação de consentimento normalmente associados à autenticação do usuário.

    if (stateChange->stateChangeType == PartyXblStateChangeType::TokenAndSignatureRequested)
    {
        auto tokenAndSignatureRequested = static_cast<PartyXblTokenAndSignatureRequestedStateChange*>(stateChange);

        // Convert the headers to the format XAL expect
        std::vector<XalHttpHeader> xalHeaders;
        for (uint32_t i = 0; i < stateChange.headerCount; ++i)
        {
            xalHeaders.push_back({stateChange.headers[i].name, stateChange.headers[i].value});
        }

        XalUserGetTokenAndSignatureArgs args = {};
        args.method = stateChange.method;
        args.url = stateChange.url;
        args.headerCount = static_cast<uint32_t>(xalHeaders.size());
        args.headers = xalHeaders.data();
        args.bodySize = stateChange.bodySize;
        args.body = static_cast<const uint8_t*>(stateChange.body);
        args.forceRefresh = stateChange.forceRefresh != 0;
        args.allUsers = stateChange.allUsers != 0;

        XAsyncBlock* asyncBlock = new XAsyncBlock;
        asyncBlock->queue = m_queue;
        HRESULT hr = XalUserGetTokenAndSignatureSilentlyAsync(m_userHandle, &args, asyncBlock);
    }

Para obter mais orientações sobre como recuperar o token e a assinatura usando a XAL, confira a documentação da XBOX Authentication Library. Depois de obter o token e a assinatura, eles podem ser fornecidos à XBOX Live Helper library chamando PartyXblManager::CompleteGetTokenAndSignatureRequest() com o mesmo correlationId fornecido ao título por meio da alteração de estado.

XBOX Services

PlayFab

Biblioteca auxiliar do XBOX Live para o PlayFab Party

Visão geral da XBOX Live Helper library

Compatibilidade com a biblioteca do PlayFab Party

Acompanhando os usuários do XBOX Live

Criando PartyLocalChatControls a partir de PartyXblLocalChatUsers

Respeitando as preferências de acessibilidade de um usuário do XBOX Live

Respeitando as configurações de privacidade e as permissões de um usuário do XBOX Live

Respeitando as permissões de comunicação entre redes

Mapeamento entre IDs de usuário do XBOX Live e IDs de entidade do PlayFab

Considerações especiais para o Windows

​Visão geral da XBOX Live Helper library

​Compatibilidade com a biblioteca do PlayFab Party

​Acompanhando os usuários do XBOX Live

​Criando PartyLocalChatControls a partir de PartyXblLocalChatUsers

​Respeitando as preferências de acessibilidade de um usuário do XBOX Live

​Respeitando as configurações de privacidade e as permissões de um usuário do XBOX Live

​Respeitando as permissões de comunicação entre redes

​Mapeamento entre IDs de usuário do XBOX Live e IDs de entidade do PlayFab

​Considerações especiais para o Windows

Visão geral da XBOX Live Helper library

Compatibilidade com a biblioteca do PlayFab Party

Acompanhando os usuários do XBOX Live

Criando PartyLocalChatControls a partir de PartyXblLocalChatUsers

Respeitando as preferências de acessibilidade de um usuário do XBOX Live

Respeitando as configurações de privacidade e as permissões de um usuário do XBOX Live

Respeitando as permissões de comunicação entre redes

Mapeamento entre IDs de usuário do XBOX Live e IDs de entidade do PlayFab

Considerações especiais para o Windows