Receiving invites

Use this topic to add game invites to your XBOX services title. To receive multiplayer invites, your game registers for the multiplayer protocol and game invite callbacks. Your game receives invites for the local user, and then joins that user to the multiplayer session.

Prerequisite

To receive game invite notifications on a Windows PC, install the XBOX Game Bar. The XBOX Game Bar app is installed by default on Windows 10, OS version 1903 or later. Select Windows Key+G to launch the XBOX Game Bar app to verify that it’s installed correctly.

If XBOX Game Bar isn’t installed on your Windows PC, you can install it from the Microsoft Store.

Registering for multiplayer protocol

Registering for multiplayer protocol tells the system how to launch your game when the user accepts a multiplayer game invite. To register the multiplayer protocol, you need to add a MultiplayerProtocol element to your MicrosoftGame.config file as shown in the following code.

    <MultiplayerProtocol>true</MultiplayerProtocol>

If you have multiple executables in the package, you can specify which executable handles the multiplayer protocol by using the Executable attribute as shown in the following code.

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

Registering for multiplayer game invite callbacks

The XGameInviteRegisterForEvent and XGameInviteUnregisterForEvent APIs are now deprecated. Use XGameActivationRegisterForEvent and XGameActivationUnregisterForEvent instead. For migration guidance, see XGameActivation.

To receive multiplayer game invite callbacks, you must register for activation callbacks by using the XGameActivationRegisterForEvent API as shown in the following code. For more information about registering and unregistering activation callbacks, see XGameActivationRegisterForEvent and 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);  
}  

To properly handle the “accepted invite from a suspended state” scenario, the title must store the inviteUri that’s passed into the OnActivation() handler method in the sample code above from the XGameActivationRegisterForEvent callback. Then the title must wait for the RegisterAppStateChangeNotification which notifies when the game has fully resumed before the title proceeds to operate on the session by using the details that are provided in the inviteUri. For more information about RegisterAppStateChangeNotification, see XBOX Game Life Cycle (NDA topic).

Parsing inviteUri from XGameActivationCallback

When your game receives the XGameActivationCallback event with an activation type of AcceptedGameInvite, you can access the inviteUri string from the XGameActivationInfo structure. The inviteUri is in one of the following formats.

For accepting a game invite

When the user accepts a game invite, the game receives the game invite callback with an inviteUri as shown in the following code.

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

The URI always starts with “ms-xbl-multiplayer//”, and then the following handles.

inviteHandleAccept indicates that the callback was initiated because the user accepted a game invite.
handle is the invite handle you use to join the multiplayer session.
invitedXuid is the ID of the XBOX services user who’s invited to the multiplayer session.
senderXuid is the ID of the XBOX services user who sent the game invite.
context is the additional (optional) context the sender might have included.

For joining a game session in progress

When the user attempts to join a multiplayer session, the game would receive an invite callback with an inviteUri as shown in the following code.

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

The URI always starts with “ms-xbl-multiplayer//”, and then the following handles.

activityHandleJoin indicates that the callback was initiated because the user accepted a game invite.
handle is the activity handle you use to join the multiplayer session.
joinerXuid is the ID of the XBOX services user who’s attempting to join the multiplayer session.
joineeXuid is the ID of the XBOX services user who’s currently in the multiplayer session.

Joining a multiplayer game session with handleId

Using Multiplayer Manager

If you’re using Multiplayer Manager, you can join the user to the multiplayer session by using the XblMultiplayerManagerJoinLobby API and passing in the handleId that’s extracted from the inviteUri. You can also use the xblUserHandle for the invitedXuid as shown in the following code.

Flat C

HRESULT hr = XblMultiplayerManagerJoinLobby(handleId, xblUserHandle);

Using Multiplayer API directly

If you’re using Multiplayer API, use the following steps to configure multiplayer sessions and invites for your title.

Fetch the multiplayer session document by using the XblMultiplayerGetSessionByHandleAsync API and pass it in the handleId.
Join the local user to the multiplayer session document by using the XblMultiplayerSessionJoin API.
Write the multiplayer session document to the service to commit this change by using the XblMultiplayerWriteSessionByHandleAsync API.

XBOX Services

PlayFab

Prerequisite

Registering for multiplayer protocol

Registering for multiplayer game invite callbacks

Flat C

Parsing inviteUri from XGameActivationCallback

For accepting a game invite

For joining a game session in progress

Joining a multiplayer game session with handleId

Using Multiplayer Manager

Flat C

Using Multiplayer API directly

Reference API documentation

See also

​Prerequisite

​Registering for multiplayer protocol

​Registering for multiplayer game invite callbacks

​Flat C

​Parsing inviteUri from XGameActivationCallback

​For accepting a game invite

​For joining a game session in progress

​Joining a multiplayer game session with handleId

​Using Multiplayer Manager

​Flat C

​Using Multiplayer API directly

​Reference API documentation

​See also

Prerequisite

Registering for multiplayer protocol

Registering for multiplayer game invite callbacks

Flat C

Parsing inviteUri from XGameActivationCallback

For accepting a game invite

For joining a game session in progress

Joining a multiplayer game session with handleId

Using Multiplayer Manager

Flat C

Using Multiplayer API directly

Reference API documentation

See also