Recepción de invitaciones

Use este tema para agregar invitaciones a partidas a su título de los servicios de XBOX. Para recibir invitaciones multijugador, su juego se registra para el protocolo multijugador y las devoluciones de llamada de invitaciones a partidas. Su juego recibe las invitaciones para el usuario local y, a continuación, une a ese usuario a la sesión multijugador.

Requisito previo

Para recibir notificaciones de invitaciones a partidas en un equipo Windows, instale la XBOX Game Bar. La aplicación XBOX Game Bar está instalada de forma predeterminada en Windows 10, versión de SO 1903 o posterior. Seleccione la tecla Windows+G para iniciar la aplicación XBOX Game Bar y comprobar que está instalada correctamente.

Si XBOX Game Bar no está instalada en su equipo Windows, puede instalarla desde el Microsoft Store.

Registro del protocolo multijugador

El registro del protocolo multijugador indica al sistema cómo iniciar su juego cuando el usuario acepta una invitación a una partida multijugador. Para registrar el protocolo multijugador, debe agregar un elemento MultiplayerProtocol a su archivo MicrosoftGame.config como se muestra en el código siguiente.

    <MultiplayerProtocol>true</MultiplayerProtocol>

Si tiene varios archivos ejecutables en el paquete, puede especificar qué ejecutable controla el protocolo multijugador mediante el atributo Executable como se muestra en el código siguiente.

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

Registro de las devoluciones de llamada de invitaciones a partidas multijugador

Las API XGameInviteRegisterForEvent y XGameInviteUnregisterForEvent están ahora en desuso. Use XGameActivationRegisterForEvent y XGameActivationUnregisterForEvent en su lugar. Para obtener guía de migración, consulte XGameActivation.

Para recibir devoluciones de llamada de invitaciones a partidas multijugador, debe registrarse para las devoluciones de llamada de activación mediante la API XGameActivationRegisterForEvent como se muestra en el código siguiente. Para obtener más información sobre cómo registrar y anular el registro de devoluciones de llamada de activación, consulte XGameActivationRegisterForEvent y XGameActivationUnregisterForEvent.

Flat C

#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 controlar correctamente el escenario de “invitación aceptada desde un estado suspendido”, el título debe almacenar el inviteUri que se pasa al método controlador OnActivation() del código de ejemplo anterior desde la devolución de llamada de XGameActivationRegisterForEvent. A continuación, el título debe esperar a RegisterAppStateChangeNotification, que notifica cuándo el juego se ha reanudado por completo, antes de que el título proceda a operar sobre la sesión mediante los detalles que se proporcionan en el inviteUri. Para obtener más información sobre RegisterAppStateChangeNotification, consulte Ciclo de vida del juego de XBOX (tema con NDA).

Análisis de inviteUri desde XGameActivationCallback

Cuando su juego recibe el evento XGameActivationCallback con un tipo de activación de AcceptedGameInvite, puede acceder a la cadena inviteUri de la estructura XGameActivationInfo. El inviteUri tiene uno de los formatos siguientes.

Para aceptar una invitación a una partida

Cuando el usuario acepta una invitación a una partida, el juego recibe la devolución de llamada de invitación a la partida con un inviteUri como se muestra en el código siguiente.

    "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="

El URI siempre comienza por “ms-xbl-multiplayer//” y, a continuación, incluye los identificadores siguientes.

inviteHandleAccept indica que la devolución de llamada se inició porque el usuario aceptó una invitación a una partida.
handle es el identificador de invitación que se usa para unirse a la sesión multijugador.
invitedXuid es el identificador del usuario de los servicios de XBOX que está invitado a la sesión multijugador.
senderXuid es el identificador del usuario de los servicios de XBOX que envió la invitación a la partida.
context es el contexto adicional (opcional) que el remitente puede haber incluido.

Para unirse a una sesión de juego en curso

Cuando el usuario intenta unirse a una sesión multijugador, el juego recibiría una devolución de llamada de invitación con un inviteUri como se muestra en el código siguiente.

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

El URI siempre comienza por “ms-xbl-multiplayer//” y, a continuación, incluye los identificadores siguientes.

activityHandleJoin indica que la devolución de llamada se inició porque el usuario aceptó una invitación a una partida.
handle es el identificador de actividad que se usa para unirse a la sesión multijugador.
joinerXuid es el identificador del usuario de los servicios de XBOX que está intentando unirse a la sesión multijugador.
joineeXuid es el identificador del usuario de los servicios de XBOX que está actualmente en la sesión multijugador.

Unirse a una sesión de juego multijugador con handleId

Uso de Multiplayer Manager

Si usa Multiplayer Manager, puede unir al usuario a la sesión multijugador mediante la API XblMultiplayerManagerJoinLobby, pasando el handleId extraído del inviteUri. También puede usar el xblUserHandle para el invitedXuid, como se muestra en el código siguiente.

Flat C

HRESULT hr = XblMultiplayerManagerJoinLobby(handleId, xblUserHandle);

Uso directo de la Multiplayer API

Si usa la Multiplayer API, siga estos pasos para configurar las sesiones multijugador y las invitaciones de su título.

Recupere el documento de sesión multijugador mediante la API XblMultiplayerGetSessionByHandleAsync y pásele el handleId.
Una al usuario local al documento de sesión multijugador mediante la API XblMultiplayerSessionJoin.
Escriba el documento de sesión multijugador en el servicio para confirmar este cambio mediante la API XblMultiplayerWriteSessionByHandleAsync.

Documentación de referencia de la API

Consulte también

API XGameActivation Control de la activación de protocolo para iniciar un juego mediante Multiplayer Manager

XBOX Services

PlayFab

Requisito previo

Registro del protocolo multijugador

Registro de las devoluciones de llamada de invitaciones a partidas multijugador

Flat C

Análisis de inviteUri desde XGameActivationCallback

Para aceptar una invitación a una partida

Para unirse a una sesión de juego en curso

Unirse a una sesión de juego multijugador con handleId

Uso de Multiplayer Manager

Flat C

Uso directo de la Multiplayer API

Documentación de referencia de la API

Consulte también

​Requisito previo

​Registro del protocolo multijugador

​Registro de las devoluciones de llamada de invitaciones a partidas multijugador

​Flat C

​Análisis de inviteUri desde XGameActivationCallback

​Para aceptar una invitación a una partida

​Para unirse a una sesión de juego en curso

​Unirse a una sesión de juego multijugador con handleId

​Uso de Multiplayer Manager

​Flat C

​Uso directo de la Multiplayer API

​Documentación de referencia de la API

​Consulte también

Requisito previo

Registro del protocolo multijugador

Registro de las devoluciones de llamada de invitaciones a partidas multijugador

Flat C

Análisis de inviteUri desde XGameActivationCallback

Para aceptar una invitación a una partida

Para unirse a una sesión de juego en curso

Unirse a una sesión de juego multijugador con handleId

Uso de Multiplayer Manager

Flat C

Uso directo de la Multiplayer API

Documentación de referencia de la API

Consulte también