XBOX Live Helper ライブラリの概要

PlayFab Party 用の XBOX Live Helper ライブラリは、PlayFab Party を使用するゲームが通信に関連する XBOX Live ポリシー (XR-015 および XR-045) を満たすのを支援するために設計されています。XBOX Live Helper ライブラリは Nuget.org で利用可能です。

PlayFab Party ライブラリとの互換性

API の破壊的変更を最小限に抑えるように努めていますが、PlayFab Party API に加えられた一部の変更により、XBOX Live Helper ライブラリが誤った値を返す可能性があります。ライブラリのバージョンに互換性があることを確認するには、以下の表を参照してください。

XBOX Live Helper Library バージョン	PlayFab Party バージョン 1.0.1	PlayFab Party バージョン 1.3.0+
1.0.1	✔
1.1.0	✔
1.2.0		✔
1.2.5		✔

XBOX Live ユーザーの追跡

PlayFab Party XBOX Live Helper ライブラリには、Party セッションに現在参加している XBOX Live ユーザーを明示的に通知する必要があります。タイトルは、マルチプレイヤーセッションドキュメントの変更をリッスンし、PartyXblManager::CreateLocalChatUser および PartyXblManager::CreateRemoteChatUser を介してその名簿を XBOX Live Helper ライブラリに反映してライブラリに通知することが推奨されます。ローカルユーザーの場合:

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;
    }
}

この時点で、対応するローカル XBOX ユーザーの PartyLocalChatControl が既に存在する場合、SetCustomContext メソッドを介してこの PartyXblLocalChatUser に関連付けることができます。

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

そうでない場合は、この新しい PartyXblLocalChatUser を使用してチャットコントロールを生成し、それらを関連付けることができます。詳細については、PartyXblLocalChatUsers からの PartyLocalChatControls の作成を参照してください。リモートユーザーの場合:

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;
    }

この時点で、対応するリモート XBOX ユーザーの PartyChatControl が既に存在する場合、SetCustomContext メソッドを介してこの PartyXblChatUser に関連付けることができます。

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

セッションドキュメントへの更新とリモートチャットコントロールのリストへの更新は順序付けられない可能性があり、リモートチャットコントロールの PartyChatControlCreatedStateChange 更新を処理する際に同様の関連付けロジックが必要になる場合があることを念頭に置いてください。ローカルおよびリモートのチャットユーザーの両方について、コア Party ライブラリはユーザーとチャットコントロールを PlayFab Entity ID で識別するのに対し、XBOX Live ヘルパーライブラリはチャットユーザーを XBOX ユーザー ID で識別することを念頭に置くことが重要です。したがって、この 2 つの間の変換がしばしば必要になります。詳細については、XBOX Live ユーザー ID と PlayFab Entity ID 間のマッピングを参照してください。

PartyXblLocalChatUsers からの PartyLocalChatControls の作成

PartyXblLocalChatUser オブジェクトは、多くの場合、Party ライブラリの PartyLocalUser および PartyLocalChatControl オブジェクトに関連付けられている場合にのみ有用です。PartyLocalUser および PartyLocalChatControl オブジェクトを生成するには、タイトルがユーザーを PlayFab にログインさせ、ユーザーの entityId と titlePlayerEntityToken を取得する必要があります。ログインは PlayFab CPP SDK を介して実行できますが、タイトルが XBOX Live 資格情報を使用して PlayFab にログインする場合は、追加の依存関係の取り込みを避けるために PartyXblManager::LoginToPlayFab を使用できます。次のサンプルは、XBOX Live Helper ライブラリが PartyXblLocalChatUser オブジェクトから PartyLocalUser および PartyLocalChatControl オブジェクトを作成するのにどのように役立つかを示しています。PartyXblLocalChatUser オブジェクトの作成の詳細については、XBOX Live ユーザーの追跡を参照してください。

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

PartyXblManager::LoginToPlayFab の呼び出し直後に、ログイン操作の結果を含む PartyXblLoginToPlayFabCompletedStateChange を受信します。

    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);

XBOX Live ユーザーのアクセシビリティ設定の尊重

PartyXblLocalChatUser オブジェクトは、Party チャットセッションに関連する XBOX Live ユーザーのアクセシビリティ設定の一部を公開します。タイトルはこの情報を使用して、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);
    }

XBOX Live ユーザーのプライバシー設定とアクセス許可の尊重

XBOX Live ポリシーに従い、タイトルは、ユーザーのプライバシーまたはアクセス許可で許可されていない場合、XBOX Live を介した通信を許可してはなりません。XBOX Live Helper ライブラリは、XBOX Live ポリシーで許可されている 2 人のユーザー間の最も制限的な PartyChatPermissionOptions を照会できるようにすることで、これを実現するのに役立ちます。この値が変更されるたびに、ライブラリによって PartyXblRequiredChatPermissionInfoChangedStateChange が生成されます。更新された PartyChatPermissionOptions は、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);

XBOX Live ヘルパーライブラリは、XBOX Live プライバシーサービスと通信することにより、各ローカルチャットユーザーに関連する各リモートチャットユーザーのプライバシーおよび特権設定を追跡します。さらに、ライブラリはリアルタイムアクティビティ更新をサブスクライブすることにより、これらの設定の変更をリッスンします。新しいリモートチャットユーザーが追加された場合、またはローカルチャットユーザーと既存のリモートチャットユーザー間のプライバシーおよび特権の関係が変更された場合、更新された PartyChatPermissionOptions 値が利用可能になったことを通知するために PartyXblRequiredChatPermissionInfoChangedStateChange が生成されます。

    // 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;
        }
    }

PartyXblChatPermissionInfo 構造体には、2 つの情報が含まれています:

PartyChatPermissionOptions マスク。PartyLocalChatControl::SetPermission() にそのまま渡すこともできますし、使用したい PartyChatPermissionOptions 値を既に持っているが、XBOX Live ポリシーを尊重していることを確認したい場合はバイナリマスクとして使用することもできます。
PartyXblChatPermissionMaskReason 値。PartyXblChatPermissionInfo::chatPermissionMask の値に関する追加情報を提供します

PartyXblChatPermissionMaskReason	説明
NoRestriction	このチャットアクセス許可に現在適用されている制限はありません。
Determining	ローカルユーザーの通信特権とプライバシー設定を判別している間、通信は制限されます
Privilege	ローカルユーザーの通信特権により、通信が制限されています。
Privacy	ターゲットチャットユーザーに関連するローカルユーザーのプライバシー設定により、通信が制限されています。
InvalidTargetUser	ターゲットユーザーが XBOX Live サービスによって有効として認識されなかったため、通信が制限されています。
XboxLiveServiceError	XBOX Live サービスに問題があるため、必要なチャットアクセス許可を正常に判別できませんでした。
UnknownError	不明な内部エラーのため、必要なチャットアクセス許可を正常に判別できませんでした。

クロスネットワーク通信のアクセス許可の尊重

XBOX Live プレイヤーと非 XBOX Live プレイヤー間のクロスネットワークプレイと通信をサポートするタイトルは、それらのプレイヤー間の通信を許可する前に、通信のアクセス許可を確認する必要があります。XBOX Live Helper ライブラリは、PartyXblLocalChatUser::GetCrossNetworkCommunicationPrivacySetting() を介してこの情報を提供します。このメソッドは、3 つの可能な値を持つ PartyXblCrossNetworkCommunicationPrivacySetting 列挙型を返します:

PartyXblCrossNetworkCommunicationPrivacySetting	説明
Allowed	この XBOX Live ユーザーのアクセス許可は、すべてのクロスネットワークプレイヤーとの通信を許可するように設定されています。
FriendsOnly	この XBOX Live ユーザーのアクセス許可は、クロスネットワークフレンドのみとの通信を許可するように設定されています。
Disallowed	この XBOX Live ユーザーのアクセス許可は、クロスネットワークプレイヤーとの通信を許可しません。

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

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

XR-015 と、クロスネットワークプレイと通信に関する詳細については、こちらを参照してください。

XBOX Live ユーザー ID と PlayFab Entity ID 間のマッピング

PlayFab Party を使用する多くの XBOX Live タイトルでは、XBOX Live ユーザー ID (XBOX Live エコシステム全体で使用される) と PlayFab Entity ID (PlayFab Party で使用される) の間で変換する必要があります。PartyXblManager::GetEntityIdsFromXboxLiveUserIds を使用すると、タイトルは、指定された XBOX Live ユーザー ID のリストに対応する PlayFab Entity ID のリストを取得できます。タイトルは、Multiplayer Session Directory のような外部名簿サービスの使用を通じて既に XBOX Live ユーザー ID のリストを持っていることが期待されます。名簿からの XBOX Live ユーザー ID をそれらの PlayFab Entity ID と関連付けることにより、ゲームセッションの名簿に対応するすべての PlayFab Entity ID のマッピングを構築できます。このマッピングを使用して、PartyEndpoint および PartyChatControl オブジェクトを対応する XBOX Live ユーザーに関連付けることができます。

各 XBOX Live ユーザー ID は、この XBOX Live ユーザーが既に PlayFab アカウントにリンクされている場合にのみ PlayFab Entity ID にマップされます。PlayFab アカウントは、特定の XBOX ユーザーに対して初めて PartyXblManager::LoginToPlayFab が呼び出されたときに自動的に作成されリンクされます。または、PlayFab SDK のコンシューマーは LoginWithXbox API を使用して同じ結果を達成できます。

ローカル PartyXblLocalChatUser は PlayFab での認証に使用されます。ユーザーが以前に PartyXblManager::LoginToPlayFab の呼び出しで PlayFab にログインしていなかった場合、XBOX Live Helper ライブラリはバックグラウンドでユーザーを認証する必要があります。

    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;
    }

PartyXblManager::GetEntityIdsFromXboxLiveUserIds の呼び出し直後に、操作の結果を含む PartyXblGetEntityIdsFromXboxLiveUserIdsCompletedStateChange を受信します。この結果を使用して、マッピングを構築または更新できます。

    // 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);

このようなマッピングを使用すると、タイトルは Party オブジェクトが 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;
}

Windows に関する特別な考慮事項

Windows では、XBOX Live Helper ライブラリは、XBOX Live トークンを取得するためにタイトルからの支援が必要です。ライブラリは PartyXblTokenAndSignatureRequestedStateChange を生成することでトークンを要求します。タイトルは XBOX Authentication Library (XAL) を使用してこれらの要求を満たすことができます。この作業をタイトルにオフロードすることで、ユーザー認証に通常関連付けられている UI 処理と同意プロンプトを完全に制御し続けることができます。

    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);
    }

XAL を使用してトークンと署名を取得する方法の詳細については、XBOX Authentication Library のドキュメントを参照してください。トークンと署名を取得したら、状態変更を介してタイトルに提供された同じ correlationId を使用して PartyXblManager::CompleteGetTokenAndSignatureRequest() を呼び出すことで、XBOX Live Helper ライブラリに提供できます。

XBOX Services

PlayFab

XBOX Live helper library for PlayFab Party

XBOX Live Helper ライブラリの概要

PlayFab Party ライブラリとの互換性

XBOX Live ユーザーの追跡

PartyXblLocalChatUsers からの PartyLocalChatControls の作成

XBOX Live ユーザーのアクセシビリティ設定の尊重

XBOX Live ユーザーのプライバシー設定とアクセス許可の尊重

クロスネットワーク通信のアクセス許可の尊重

XBOX Live ユーザー ID と PlayFab Entity ID 間のマッピング

Windows に関する特別な考慮事項

​XBOX Live Helper ライブラリの概要

​PlayFab Party ライブラリとの互換性

​XBOX Live ユーザーの追跡

​PartyXblLocalChatUsers からの PartyLocalChatControls の作成

​XBOX Live ユーザーのアクセシビリティ設定の尊重

​XBOX Live ユーザーのプライバシー設定とアクセス許可の尊重

​クロスネットワーク通信のアクセス許可の尊重

​XBOX Live ユーザー ID と PlayFab Entity ID 間のマッピング

​Windows に関する特別な考慮事項

XBOX Live Helper ライブラリの概要

PlayFab Party ライブラリとの互換性

XBOX Live ユーザーの追跡

PartyXblLocalChatUsers からの PartyLocalChatControls の作成

XBOX Live ユーザーのアクセシビリティ設定の尊重

XBOX Live ユーザーのプライバシー設定とアクセス許可の尊重

クロスネットワーク通信のアクセス許可の尊重

XBOX Live ユーザー ID と PlayFab Entity ID 間のマッピング

Windows に関する特別な考慮事項