ソーシャルマネージャーの概要 - XBOX Game Development Documentation

このトピックでは、XBOX services Social Manager API がオンラインのフレンドとそのゲームアクティビティの追跡をどのように簡素化するかについて説明します。 XBOX services は、さまざまなシナリオでタイトルが使用できる豊富なソーシャルグラフを提供します。 XBOX Services API (XSAPI) のソーシャル API を使用してソーシャルグラフに関する情報を取得および維持することは複雑です。この情報を最新に保つことは煩雑になる可能性があります。これを正しく行わないと、パフォーマンスの問題、古いデータ、または XBOX services のソーシャルサービスを必要以上に頻繁に呼び出したことによるスロットリングが発生する可能性があります。 Social Manager は以下によってこの問題を解決します:

シンプルに呼び出せる API を作成する。
バックグラウンドで Real-Time Activity (RTA) サービスを使用して最新の情報を作成する。
開発者はサービスへの余分な負荷を掛けることなく、Social Manager API を同期的に呼び出すことができる。

Social Manager は、複数の RTA サブスクリプションを扱う複雑さや、ユーザーのデータをリフレッシュする作業を隠蔽し、開発者が必要な最新のグラフを簡単に取得できるようにすることで、興味深いシナリオを実現します。詳細については、「ソーシャルマネージャーのメモリとパフォーマンス」を参照してください。

機能

Social Manager は以下の機能を提供します。

簡素化されたソーシャル API
最新のソーシャルグラフ
表示される情報の詳細度の制御
XBOX services への呼び出し回数の削減
- これはデータ取得の全体的なレイテンシの削減に直接関係します
スレッドセーフ
データを効率的に最新の状態に保つ

主要な概念

ソーシャルグラフ: ソーシャルグラフ はデバイス上のローカルユーザーに対して作成されます。これにより、ユーザーのすべてのフレンドに関する情報を最新に保つ構造が作成されます。

Windows では、ローカルユーザーは 1 人だけ持てます。

XBOX ソーシャルユーザー: XBOX ソーシャルユーザー は、グループ内のユーザーに関連付けられたソーシャルデータの完全なセットです。 XBOX ソーシャルユーザーグループ: グループは、UI の生成などに使用されるユーザーの集合です。グループには 2 つの種類があります:

フィルターグループ: フィルターグループ はローカル (呼び出し) ユーザーの ソーシャルグラフ を取り、指定されたフィルターパラメーターに基づいて常に最新のユーザーセットを返します。
リストグループ: リストグループ はユーザーのリストを取り、それらのユーザーの常に最新のビューを返します。これらのユーザーはユーザーのフレンドリスト外にいてもかまいません。

ソーシャルユーザーグループ を最新に保つには、XblSocialManagerDoWork 関数を毎フレーム呼び出す必要があります。

API の概要

最も頻繁に使用する主要な API は以下のとおりです。

フラット C API 関数: XblSocialManagerAddLocalUser

Social Manager にローカルユーザーを追加すると、そのユーザーの ソーシャルグラフ が作成されます。ローカルユーザーが追加された後、そのユーザーに対して ソーシャルユーザーグループ を作成できます。 Social Manager は XBOX ソーシャルユーザーグループを最新に保ち、ユーザーグループをプレゼンスやユーザーとの関係でフィルターできます。たとえば、オンラインで現在のタイトルをプレイしているすべてのフレンドを含む XBOX ソーシャルユーザーグループを作成できます。これは、フレンドがタイトルのプレイを開始または停止するにつれて最新に保たれます。

XBOX ソーシャルユーザーグループ

フラット C API 関数: XblSocialManagerAddLocalUser

XBOX ソーシャルユーザーグループは、前述のように特定の条件を満たすユーザーのグループです。 XBOX ソーシャルユーザーグループは、グループの種類、どのユーザーが追跡されているかまたはグループに設定されているフィルター、およびグループが属するローカルユーザーを公開します。 Social Manager API の完全な説明は XBOX Live API リファレンスで確認できます。また、API は XblSocialManager プレフィックスのドキュメントでも確認できます。

使用方法

フィルターからソーシャルユーザーグループを作成する

このシナリオでは、ユーザーのフレンドのリストや、ユーザーがお気に入りとしてタグ付けしたフレンドのサブセットなど、フィルターからユーザーのリストを取得します。 フラット C API

HRESULT hr = XblSocialManagerAddLocalUser(user, extraLevelDetail, nullptr);

XblPresenceFilter presenceFilter{ XblPresenceFilter::All };
XblRelationshipFilter relationshipFilter{ XblRelationshipFilter::Friends };

XblSocialManagerUserGroupHandle groupHandle{ nullptr };
HRESULT hr = XblSocialManagerCreateSocialUserGroupFromFilters(user, presenceFilter, relationshipFilter, &groupHandle);

if (SUCCEEDED(hr))
{
    state.groups.insert(groupHandle);
}

// Some update loop in the game.
while (true)
{
    const XblSocialManagerEvent* events{ nullptr };
    size_t eventCount{ 0 };
    HRESULT hr = XblSocialManagerDoWork(&events, &eventCount);
    if (SUCCEEDED(hr))
    {
        for (size_t i = 0; i < eventCount; i++)
        {
            // Act on the event.
        }
    }
}

詳細については、以下を参照してください。

返されるイベント

ローカルユーザー追加: ユーザーのソーシャルグラフの読み込みが完了したときにトリガーされます。初期化中にエラーが発生したかどうかを示します。

フラット C API: XblSocialManagerEventType::LocalUserAdded

ソーシャルユーザーグループ読み込み: ソーシャルユーザーグループが作成されたときにトリガーされます。

フラット C API: XblSocialManagerEventType::SocialUserGroupLoaded

ソーシャルグラフへのユーザー追加: ユーザーが読み込まれるときにトリガーされます。

フラット C API: XblSocialManagerEventType::UsersAddedToSocialGraph

詳細については、以下を参照してください。

XblSocialManagerEventType (フラット C API)

追加の詳細

フラット C API 前の例は、ユーザーに対して Social Manager を初期化し、そのユーザーのソーシャルユーザーグループを作成し、最新の状態に保つ方法を示しています。フィルターオプションは XblPresenceFilter と XblRelationshipFilter の列挙型です。ゲームループ内では、XblSocialManagerDoWork 関数が作成されたすべてのビューを、そのグループ内のユーザーの最新のスナップショットで更新します。ビュー内のユーザーは、XblSocialManagerUserGroupGetUsers 関数を呼び出すことで取得できます。これは、XSAPI が所有する XblSocialManagerUser オブジェクトの配列である XblSocialManagerUserPtrArray を返します。 XblSocialManagerUser には、ゲーマータグ、ゲーマーピック、URI などのソーシャル情報が含まれています。

リストからソーシャルユーザーグループを作成および更新する

このシナリオでは、マルチプレイヤーセッション内のユーザーなど、ユーザーのリストのソーシャル情報を取得します。 フラット C API

HRESULT hr = XblSocialManagerAddLocalUser(user, extraLevelDetail, nullptr);

// List of xuids to track.
std::vector<uint64_t> xuids
{
    listXuids.begin() + static_cast<int>(offset),
    listXuids.begin() + static_cast<int>(offset + count) 
}; 

XblSocialManagerUserGroupHandle groupHandle{ nullptr };
HRESULT hr = XblSocialManagerCreateSocialUserGroupFromList(user, xuids.data(), xuids.size(), &groupHandle);

if (SUCCEEDED(hr))
{
    state.groups.insert(groupHandle);
}

// Some update loop in the game.
while (true)
{
    const XblSocialManagerEvent* events{ nullptr };
    size_t eventCount{ 0 };
    HRESULT hr = XblSocialManagerDoWork(&events, &eventCount);
    if (SUCCEEDED(hr))
    {
        for (size_t i = 0; i < eventCount; i++)
        {
            // Act on the event
        }
    }
}

詳細については、以下を参照してください。

返されるイベント

リストからのソーシャルユーザーグループを更新する

XblSocialManagerUpdateSocialUserGroup を呼び出すことで、ソーシャルユーザーグループ内の追跡ユーザーのリストを変更することもできます。 フラット C API

// New list of xuids to track.
std::vector<uint64_t> xuids
{ 
    listXuids.begin() + static_cast<int>(offset),
    listXuids.begin() + static_cast<int>(offset + count)
};

HRESULT hr = XblSocialManagerUpdateSocialUserGroup(group, xuids.data(), xuids.size());

// Some update loop in the game.
while (true)
{
    const XblSocialManagerEvent* events{ nullptr };
    size_t eventCount{ 0 };
    HRESULT hr = XblSocialManagerDoWork(&events, &eventCount);
    if (SUCCEEDED(hr))
    {
        for (size_t i = 0; i < eventCount; i++)
        {
            // Act on the event.
        }
    }
}

詳細については、以下を参照してください。

返されるイベント

ソーシャルユーザーグループ更新: ソーシャルユーザーグループの更新が完了したときにトリガーされます。

C++: social_user_group_updated
C: XblSocialManagerEventType::SocialUserGroupUpdated

ソーシャルグラフへのユーザー追加: ユーザーが読み込まれるときにトリガーされます。リスト経由で追加したユーザーがすでにグラフ内にある場合、このイベントはトリガーされません。

C++: users_added_to_social_graph
C: XblSocialManagerEventType::UsersAddedToSocialGraph

ソーシャルグラフからのユーザー削除: 以前のユーザーがソーシャルグラフから削除されたときにトリガーされます。

C: XblSocialManagerEventType::UsersRemovedFromSocialGraph

Social Manager はイベントの形で何が起きたかを通知します。これらのイベントを使って、UI を更新したり、その他のロジックを実行したりできます。 フラット C API

// Some update loop in the game.
while (true)
{
    const XblSocialManagerEvent* events{ nullptr };
    size_t eventCount{ 0 };
    HRESULT hr = XblSocialManagerDoWork(&events, &eventCount);
    if (SUCCEEDED(hr))
    {
        for (size_t i = 0; i < eventCount; i++)
        {
            // Act on the event.
            auto& socialEvent = events[i];
            std::stringstream ss;
            ss << "XblSocialManagerDoWork: Event of type " << eventTypesMap[socialEvent.eventType] << std::endl;
            for (uint32_t i = 0; i < XBL_SOCIAL_MANAGER_MAX_AFFECTED_USERS_PER_EVENT; i++)
            {
                if (socialEvent.usersAffected[i] != nullptr)
                {
                    if (i == 0)
                    {
                        ss << "Users affected: " << std::endl;
                    }
                    ss << "\t" << socialEvent.usersAffected[i]->gamertag << std::endl;
                }
            }
            LogToFile(ss.str().c_str());
        }
    }
}

詳細については、以下を参照してください。

返されるイベント

XblSocialManagerEventType::LocalUserAdded。ユーザーのソーシャルグラフの読み込みが完了したときにトリガーされます。初期化中にエラーが発生したかどうかを示します。 XblSocialManagerEventType::SocialUserGroupLoaded。ソーシャルユーザーグループが作成されたときにトリガーされます。 XblSocialManagerEventType::UsersAddedToSocialGraph。ユーザーが読み込まれるときにトリガーされます。 XblSocialManagerEventType::UsersRemovedFromSocialGraph。ユーザーがソーシャルグラフから削除されたときにトリガーされます。 XblSocialManagerEventType::PresenceChanged。ソーシャルグラフ内のユーザーのプレゼンスが変化したときにトリガーされます。 XblSocialManagerEventType::ProfilesChanged。ソーシャルグラフ内のユーザーのプロファイルが変化したときにトリガーされます。 XblSocialManagerEventType::SocialRelationshipsChanged。ローカルユーザーとソーシャルグラフ内の別のユーザーとの関係が変化したときにトリガーされます。 XblSocialManagerEventType::SocialUserGroupUpdated。ソーシャルユーザーグループの更新が完了したときにトリガーされます。

追加の詳細

この例は、Social Manager が提供する追加の制御の一部を示しています。ゲームループ中に最新のユーザーリストを提供するためにソーシャルユーザーグループフィルターに依存する代わりに、ソーシャルグラフはゲームループの外側で初期化されます。その後、タイトルは XblSocialManagerDoWork 関数によって返される イベント に依存します。 Events は XblSocialManagerEvent のリストです。各 XblSocialManagerEvent には、直前のフレーム中に発生したソーシャルグラフへの変更が含まれています。たとえば、XblSocialManagerEventType::ProfilesChanged と XblSocialManagerEventType::UsersAddedToSocialGraph などです。詳細については、XblSocialManagerEvent の API ドキュメントを参照してください。

クリーンアップ

ソーシャルユーザーグループのクリーンアップ

以下の例は、作成されたソーシャルユーザーグループをクリーンアップします。呼び出し側は、作成されたソーシャルユーザーグループへの参照がある場合、それらもすべて削除する必要があります。それらは無効になるためです。 フラット C API

HRESULT hr = XblSocialManagerDestroySocialUserGroup(groupHandle);
if (SUCCEEDED(hr))
{
    state.groups.erase(groupHandle);
}

詳細については、以下を参照してください。

XblSocialManagerDestroySocialUserGroup

ローカルユーザーのクリーンアップ

以下の例に示すように、ローカルユーザーを削除すると、読み込まれたユーザーのソーシャルグラフと、そのユーザーを使って作成されたソーシャルユーザーグループが削除されます。フラット C API では、削除されたユーザーに関するイベントはこれ以上受け取りません。 フラット C API

HRESULT hr = XblSocialManagerRemoveLocalUser(user);

詳細については、以下を参照してください。

XblSocialManagerRemoveLocalUser

​機能

​主要な概念

​API の概要

​Social Manager にローカル ユーザーを追加する

​XBOX ソーシャル ユーザー グループ

​使用方法

​フィルターからソーシャル ユーザー グループを作成する

​返されるイベント

​追加の詳細

​リストからソーシャル ユーザー グループを作成および更新する

​返されるイベント

​リストからのソーシャル ユーザー グループを更新する

​返されるイベント

​Social Manager イベントの使用

​返されるイベント

​追加の詳細

​クリーンアップ

​ソーシャル ユーザー グループのクリーンアップ

​ローカル ユーザーのクリーンアップ

機能

主要な概念

API の概要

Social Manager にローカルユーザーを追加する

XBOX ソーシャルユーザーグループ

使用方法

フィルターからソーシャルユーザーグループを作成する

返されるイベント

追加の詳細

リストからソーシャルユーザーグループを作成および更新する

返されるイベント

リストからのソーシャルユーザーグループを更新する

返されるイベント

Social Manager イベントの使用

返されるイベント

追加の詳細

クリーンアップ

ソーシャルユーザーグループのクリーンアップ

ローカルユーザーのクリーンアップ