Recebendo convites

Use este tópico para adicionar convites de jogo ao seu título dos serviços do XBOX. Para receber convites multiplayer, seu jogo se registra no protocolo multiplayer e nos retornos de chamada de convite de jogo. Seu jogo recebe convites para o usuário local e, em seguida, adiciona esse usuário à sessão multiplayer.

Pré-requisito

Para receber notificações de convite de jogo em um PC com Windows, instale a XBOX Game Bar. O aplicativo XBOX Game Bar é instalado por padrão no Windows 10, versão 1903 ou posterior do sistema operacional. Pressione tecla Windows+G para iniciar o aplicativo XBOX Game Bar e verificar se ele está instalado corretamente.

Se a XBOX Game Bar não estiver instalada no seu PC com Windows, você pode instalá-la pela Microsoft Store.

Registrando o protocolo multiplayer

Registrar o protocolo multiplayer informa ao sistema como iniciar seu jogo quando o usuário aceita um convite de jogo multiplayer. Para registrar o protocolo multiplayer, você precisa adicionar um elemento MultiplayerProtocol ao arquivo MicrosoftGame.config, conforme mostrado no código a seguir.

    <MultiplayerProtocol>true</MultiplayerProtocol>

Se você tiver vários executáveis no pacote, poderá especificar qual executável trata o protocolo multiplayer usando o atributo Executable, conforme mostrado no código a seguir.

    <MultiplayerProtocol Executable="MyExecutableForMultiplayer.exe">true</MultiplayerProtocol>

Registrando os retornos de chamada de convite de jogo multiplayer

As APIs XGameInviteRegisterForEvent e XGameInviteUnregisterForEvent foram preteridas. Em vez delas, use XGameActivationRegisterForEvent e XGameActivationUnregisterForEvent. Para obter orientações sobre a migração, consulte XGameActivation.

Para receber retornos de chamada de convite de jogo multiplayer, você deve se registrar para retornos de chamada de ativação usando a API XGameActivationRegisterForEvent, conforme mostrado no código a seguir. Para obter mais informações sobre como registrar e cancelar o registro de retornos de chamada de ativação, consulte XGameActivationRegisterForEvent e XGameActivationUnregisterForEvent.

API C simples

#include <XTaskQueue.h>
#include <XGameActivation.h>  
  
XTaskQueueHandle g_taskQueue;  
XTaskQueueRegistrationToken g_activationToken;  
  
void CALLBACK OnActivation(void* context, const XGameActivationInfo* activationInfo)  
{  
    if (activationInfo->type == XGameActivationType::AcceptedGameInvite)
    {
        if (activationInfo->inviteUri != nullptr)
        {
            std::string inviteString(activationInfo->inviteUri);
            auto pos = inviteString.find("handle=");
            auto handleId = inviteString.substr(pos + 7, 36);
            // Now call XblMultiplayerManagerJoinLobby
        }
    }
}  
  
void InitializeGame()  
{  
    XGameActivationRegisterForEvent(g_taskQueue, nullptr, OnActivation, &g_activationToken);  
}  
  
void ShutdownGame()  
{  
    XGameActivationUnregisterForEvent(g_activationToken, true);  
}  

Para tratar corretamente o cenário de “convite aceito a partir de um estado suspenso”, o título deve armazenar o inviteUri passado para o método manipulador OnActivation() no código de exemplo acima, proveniente do retorno de chamada de XGameActivationRegisterForEvent. Em seguida, o título deve aguardar a RegisterAppStateChangeNotification, que notifica quando o jogo foi totalmente retomado, antes de prosseguir com operações na sessão usando os detalhes fornecidos no inviteUri. Para obter mais informações sobre RegisterAppStateChangeNotification, consulte Ciclo de vida de jogos do XBOX (tópico sob NDA).

Analisando o inviteUri de XGameActivationCallback

Quando seu jogo recebe o evento XGameActivationCallback com o tipo de ativação AcceptedGameInvite, você pode acessar a cadeia de caracteres inviteUri na estrutura XGameActivationInfo. O inviteUri está em um dos formatos a seguir.

Para aceitar um convite de jogo

Quando o usuário aceita um convite de jogo, o jogo recebe o retorno de chamada de convite de jogo com um inviteUri, conforme mostrado no código a seguir.

    "ms-xbl-multiplayer://inviteHandleAccept?handle=%s&invitedXuid=%s&senderXuid=%s&context=%s"
    
    // for example:
    // "ms-xbl-multiplayer://inviteHandleAccept?handle=00000000-0000-1234-5678-1234567890ab&invitedXuid=1234567890123456&senderXuid=6543210987654321&context="

O URI sempre começa com “ms-xbl-multiplayer//”, seguido dos identificadores a seguir.

inviteHandleAccept indica que o retorno de chamada foi iniciado porque o usuário aceitou um convite de jogo.
handle é o identificador de convite que você usa para ingressar na sessão multiplayer.
invitedXuid é o ID do usuário dos serviços do XBOX que foi convidado para a sessão multiplayer.
senderXuid é o ID do usuário dos serviços do XBOX que enviou o convite de jogo.
context é o contexto adicional (opcional) que o remetente pode ter incluído.

Para ingressar em uma sessão de jogo em andamento

Quando o usuário tenta ingressar em uma sessão multiplayer, o jogo recebe um retorno de chamada de convite com um inviteUri, conforme mostrado no código a seguir.

    "ms-xbl-multiplayer://activityHandleJoin?&handle=%s&joinerXuid=%s&joineeXuid=%s"

O URI sempre começa com “ms-xbl-multiplayer//”, seguido dos identificadores a seguir.

activityHandleJoin indica que o retorno de chamada foi iniciado porque o usuário aceitou um convite de jogo.
handle é o identificador de atividade que você usa para ingressar na sessão multiplayer.
joinerXuid é o ID do usuário dos serviços do XBOX que está tentando ingressar na sessão multiplayer.
joineeXuid é o ID do usuário dos serviços do XBOX que está atualmente na sessão multiplayer.

Ingressando em uma sessão de jogo multiplayer com handleId

Usando o Multiplayer Manager

Se você estiver usando o Multiplayer Manager, poderá adicionar o usuário à sessão multiplayer usando a API XblMultiplayerManagerJoinLobby e passando o handleId extraído do inviteUri. Você também pode usar o xblUserHandle para o invitedXuid, conforme mostrado no código a seguir.

API C simples

HRESULT hr = XblMultiplayerManagerJoinLobby(handleId, xblUserHandle);

Usando a API Multiplayer diretamente

Se você estiver usando a API Multiplayer, siga as etapas a seguir para configurar sessões multiplayer e convites para o seu título.

Busque o documento da sessão multiplayer usando a API XblMultiplayerGetSessionByHandleAsync e passe o handleId para ela.
Adicione o usuário local ao documento da sessão multiplayer usando a API XblMultiplayerSessionJoin.
Grave o documento da sessão multiplayer no serviço para confirmar essa alteração usando a API XblMultiplayerWriteSessionByHandleAsync.

Documentação de referência da API

Confira também

API XGameActivation Tratando a ativação de protocolo para iniciar um jogo usando o Multiplayer Manager

XBOX Services

PlayFab

Pré-requisito

Registrando o protocolo multiplayer

Registrando os retornos de chamada de convite de jogo multiplayer

API C simples

Analisando o inviteUri de XGameActivationCallback

Para aceitar um convite de jogo

Para ingressar em uma sessão de jogo em andamento

Ingressando em uma sessão de jogo multiplayer com handleId

Usando o Multiplayer Manager

API C simples

Usando a API Multiplayer diretamente

Documentação de referência da API

Confira também

​Pré-requisito

​Registrando o protocolo multiplayer

​Registrando os retornos de chamada de convite de jogo multiplayer

​API C simples

​Analisando o inviteUri de XGameActivationCallback

​Para aceitar um convite de jogo

​Para ingressar em uma sessão de jogo em andamento

​Ingressando em uma sessão de jogo multiplayer com handleId

​Usando o Multiplayer Manager

​API C simples

​Usando a API Multiplayer diretamente

​Documentação de referência da API

​Confira também

Pré-requisito

Registrando o protocolo multiplayer

Registrando os retornos de chamada de convite de jogo multiplayer

API C simples

Analisando o inviteUri de XGameActivationCallback

Para aceitar um convite de jogo

Para ingressar em uma sessão de jogo em andamento

Ingressando em uma sessão de jogo multiplayer com handleId

Usando o Multiplayer Manager

API C simples

Usando a API Multiplayer diretamente

Documentação de referência da API

Confira também