招待の受信

このトピックでは、XBOX services タイトルにゲーム招待を追加する方法について説明します。マルチプレイヤー招待を受信するには、ゲームがマルチプレイヤープロトコルとゲーム招待コールバックを登録します。ゲームはローカルユーザー宛ての招待を受信し、そのユーザーをマルチプレイヤーセッションに参加させます。

前提条件

Windows PC でゲーム招待通知を受信するには、XBOX Game Bar をインストールします。XBOX Game Bar アプリは、Windows 10 OS バージョン 1903 以降には既定でインストールされています。Windows キー+G キーを押して XBOX Game Bar アプリを起動し、正しくインストールされていることを確認します。

XBOX Game Bar が Windows PC にインストールされていない場合は、Microsoft Store からインストールできます。

マルチプレイヤープロトコルの登録

マルチプレイヤープロトコルを登録すると、ユーザーがマルチプレイヤーゲーム招待を承諾したときにシステムがゲームをどのように起動すべきかがわかります。マルチプレイヤープロトコルを登録するには、次のコードのように、MicrosoftGame.config ファイルに MultiplayerProtocol 要素を追加する必要があります。

    <MultiplayerProtocol>true</MultiplayerProtocol>

パッケージ内に複数の実行可能ファイルがある場合は、次のコードのように、Executable 属性を使用して、どの実行可能ファイルがマルチプレイヤープロトコルを処理するかを指定できます。

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

マルチプレイヤーゲーム招待コールバックの登録

XGameInviteRegisterForEvent および XGameInviteUnregisterForEvent API は非推奨になりました。代わりに XGameActivationRegisterForEvent および XGameActivationUnregisterForEvent を使用してください。移行に関するガイダンスについては、XGameActivation を参照してください。

マルチプレイヤーゲーム招待コールバックを受信するには、次のコードのように、XGameActivationRegisterForEvent API を使用してアクティベーションコールバックを登録する必要があります。アクティベーションコールバックの登録と登録解除の詳細については、XGameActivationRegisterForEvent および 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);  
}  

「サスペンド状態から招待を承諾する」シナリオを適切に処理するために、タイトルは、上のサンプルコードで XGameActivationRegisterForEvent コールバックから OnActivation() ハンドラーメソッドに渡される inviteUri を保存する必要があります。その後、タイトルは、ゲームが完全に再開されたことを通知する RegisterAppStateChangeNotification を待機してから、inviteUri で提供される詳細を使用してセッションの操作に進む必要があります。 RegisterAppStateChangeNotification の詳細については、XBOX ゲームライフサイクル (NDA トピック) を参照してください。

XGameActivationCallback からの inviteUri の解析

ゲームがアクティベーションタイプ AcceptedGameInvite で XGameActivationCallback イベントを受信すると、XGameActivationInfo 構造体から inviteUri 文字列にアクセスできます。inviteUri は次のいずれかの形式です。

ゲーム招待を承諾する場合

ユーザーがゲーム招待を承諾すると、ゲームは次のコードに示すような inviteUri を含むゲーム招待コールバックを受信します。

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

URI は常に “ms-xbl-multiplayer//” で始まり、その後に次のハンドルが続きます。

inviteHandleAccept は、ユーザーがゲーム招待を承諾したためにコールバックが開始されたことを示します。
handle は、マルチプレイヤーセッションへの参加に使用する招待ハンドルです。
invitedXuid は、マルチプレイヤーセッションに招待された XBOX services ユーザーの ID です。
senderXuid は、ゲーム招待を送信した XBOX services ユーザーの ID です。
context は、送信者が含めた可能性のある追加の (オプションの) コンテキストです。

進行中のゲームセッションに参加する場合

ユーザーがマルチプレイヤーセッションへの参加を試みると、ゲームは次のコードに示すような inviteUri を含む招待コールバックを受信します。

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

URI は常に “ms-xbl-multiplayer//” で始まり、その後に次のハンドルが続きます。

activityHandleJoin は、ユーザーがゲーム招待を承諾したためにコールバックが開始されたことを示します。
handle は、マルチプレイヤーセッションへの参加に使用するアクティビティハンドルです。
joinerXuid は、マルチプレイヤーセッションに参加しようとしている XBOX services ユーザーの ID です。
joineeXuid は、現在マルチプレイヤーセッションにいる XBOX services ユーザーの ID です。

handleId を使用したマルチプレイヤーゲームセッションへの参加

Multiplayer Manager の使用

Multiplayer Manager を使用している場合は、次のコードに示すように、XblMultiplayerManagerJoinLobby API を使用して、inviteUri から抽出された handleId を渡すことにより、ユーザーをマルチプレイヤーセッションに参加させることができます。また、invitedXuid には xblUserHandle を使用することもできます。

Flat C

HRESULT hr = XblMultiplayerManagerJoinLobby(handleId, xblUserHandle);

Multiplayer API の直接使用

Multiplayer API を使用している場合は、次の手順に従って、タイトルのマルチプレイヤーセッションと招待を構成します。

XblMultiplayerGetSessionByHandleAsync API を使用してマルチプレイヤーセッションドキュメントを取得し、handleId を渡します。
XblMultiplayerSessionJoin API を使用して、ローカルユーザーをマルチプレイヤーセッションドキュメントに参加させます。
XblMultiplayerWriteSessionByHandleAsync API を使用して、この変更をコミットするためにマルチプレイヤーセッションドキュメントをサービスに書き込みます。

XBOX Services

PlayFab

前提条件

マルチプレイヤープロトコルの登録

マルチプレイヤーゲーム招待コールバックの登録

Flat C

XGameActivationCallback からの inviteUri の解析

ゲーム招待を承諾する場合

進行中のゲームセッションに参加する場合

handleId を使用したマルチプレイヤーゲームセッションへの参加

Multiplayer Manager の使用

Flat C

Multiplayer API の直接使用

リファレンス API ドキュメント

関連項目

​前提条件

​マルチプレイヤー プロトコルの登録

​マルチプレイヤー ゲーム招待コールバックの登録

​Flat C

​XGameActivationCallback からの inviteUri の解析

​ゲーム招待を承諾する場合

​進行中のゲーム セッションに参加する場合

​handleId を使用したマルチプレイヤー ゲーム セッションへの参加

​Multiplayer Manager の使用

​Flat C

​Multiplayer API の直接使用

​リファレンス API ドキュメント

​関連項目

前提条件

マルチプレイヤープロトコルの登録

マルチプレイヤーゲーム招待コールバックの登録

Flat C

XGameActivationCallback からの inviteUri の解析

ゲーム招待を承諾する場合

進行中のゲームセッションに参加する場合

handleId を使用したマルチプレイヤーゲームセッションへの参加

Multiplayer Manager の使用

Flat C

Multiplayer API の直接使用

リファレンス API ドキュメント

関連項目