Social Manager の概要

このトピックでは、Xbox サービス Social Manager API を使用して、オンラインのフレンドとそのゲーム アクティビティの追跡を簡素化する方法について説明します。

Xbox サービスは、タイトルでさまざまなシナリオに使用できるリッチなソーシャル グラフを提供します。 Xbox サービス API (XSAPI) でソーシャル API を使用してソーシャル グラフに関する情報を取得し維持するのは複雑です。 この情報を最新の状態に保つことが複雑になる場合があります。 間違った方法でこれを行うと、パフォーマンスの問題、古いデータの使用、また、Xbox サービス ソーシャル サービスの呼び出しが必要以上に多いことが原因によるスロットリングが発生する可能性があります。

Social Manager は、以下の方法でこの問題を解決します。

• 呼び出しがシンプルな API を作成する。
• バックグラウンドでリアルタイム アクティビティ (RTA) サービスを使用して最新の情報を作成する。
• 開発者は、サービスに余計な負荷をかけることなく、Social Manager API を同期的に呼び出すことができる。

Social Manager は、複数の RTA サブスクリプションの処理とユーザー用データの更新の複雑さを隠し、興味深いシナリオを作成するために必要な最新のグラフをデベロッパーが容易に取得できるようにします。

詳細については、「Social Manager のメモリとパフォーマンス」をご覧ください。

機能

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

• 簡素化されたソーシャル API
• 最新のソーシャル グラフ
• 表示される情報の詳しさを制御する
• Xbox サービスの呼び出し回数を減らしました
  • これはデータ取得における全体的な遅延低減に直接関係する
• スレッド セーフ
• データを効率良く最新の状態に保つ

主要な概念

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

注意

Windows ではローカル ユーザーは 1 人しか存在できません。

Xbox ソーシャル ユーザー: Xbox ソーシャル ユーザー は、グループのユーザーと関連付けられるソーシャル データの完全なセットです。

Xbox ソーシャル ユーザー グループ: グループは、UI への表示などに使用されるユーザーの集団です。 次の 2 種類のグループがあります。

• フィルター グループ: フィルター グループ はローカル (呼び出し側) ユーザーの ソーシャル グラフ を入力として、指定されたフィルター パラメーターに基づいて、常に最新のユーザー セットを返します。

• リスト グループ: リスト グループ は、ユーザーのリストを受け取り、常にそれらのユーザーの最新のビューを返します。 これらのユーザーは、ユーザーのフレンド リストに含まれていなくてもかまいません。

ソーシャル ユーザー グループ を常に最新の状態に維持するには、XblSocialManagerDoWork 関数をフレームごとに呼び出す必要があります。

API 概要

最も頻繁に使用されるのは、次の主要な API です。

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

• フラット C API 関数: XblSocialManagerAddLocalUser

Social Manager にローカル ユーザーを追加すると、そのユーザーの ソーシャル グラフ が作成されます。 ローカル ユーザーを追加した後、そのユーザーに対するソーシャル ユーザー グループを作成できます。

Social Manager は Xbox ソーシャル ユーザー グループを最新の状態に保ち、プレゼンスまたはユーザーとの関係によってユーザー グループをフィルタリングできます。 たとえば、ユーザーのフレンドのうち、オンラインであり、現在のタイトルをプレイしている全員を含む Xbox ソーシャル ユーザー グループを作成できます。 フレンドがタイトルのプレイを開始または停止すると、このビューが最新の状態に更新されます。

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

• フラット C API 関数: XblSocialManagerAddLocalUser

Xbox ソーシャル ユーザー グループは、前述のように、特定の条件を満たすユーザーのグループのことです。 Xbox のソーシャル ユーザー グループは、グループのタイプ、追跡中のユーザーまたはグループに設定されているフィルター、および、グループが属するローカル ユーザーを公開します。

ソーシャル マネージャ API の詳細説明については、「Xbox Live API リファレンス」を参照してください。 XblSocialManager プレフィックスのドキュメントでも API を確認できます。

使用法

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

このシナリオで、このユーザーがフォローしている、またはお気に入りとしてタグ付けされたすべての人物など、フィルターからユーザーの一覧を作成します。

フラット 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.
        }
    }
}

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

• XblPresenceFilter
• XblRelationshipFilter
• XblSocialManagerAddLocalUser
• XblSocialManagerCreateSocialUserGroupFromFilters
• XblSocialManagerDoWork
• XblSocialManagerEvent

返されたイベント

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

• Flat C API: XblSocialManagerEventType::LocalUserAdded

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

• Flat C API: XblSocialManagerEventType::SocialUserGroupLoaded

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

• Flat C API: XblSocialManagerEventType::UsersAddedToSocialGraph

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

• XblSocialManagerEventType (フラット C API)

その他の詳細

フラット C API 前の例では、ユーザーのソーシャル マネージャーを初期化し、そのユーザーのソーシャル ユーザー グループを作成し、最新の状態に維持する方法を示します。

フィルター オプションは、XblPresenceFilter および XblRelationshipFilter の列挙です。

ゲーム ループでは、 XblSocialManagerDoWork 関数が、そのグループ内のユーザーの最新のスナップショットを用いて、生成したビューすべてを更新します。

ビュー内のユーザーは、XblSocialManagerUserGroupGetUsers 関数を呼び出すことによって取得できます。 XSAPI が所有する XblSocialManagerUser オブジェクトの配列である XblSocialManagerUserPtrArray を返します。 XblSocialManagerUser には、ゲーマータグ、gamerpic、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
        }
    }
}

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

• XblSocialManagerAddLocalUser
• XblSocialManagerCreateSocialUserGroupFromList
• XblSocialManagerDoWork
• XblSocialManagerEvent

返されたイベント

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

XblSocialManagerEventType::SocialUserGroupLoaded。 ソーシャル ユーザー グループが作成され、追跡対象のユーザーがソーシャル グラフに追加されるとトリガーされます。

XblSocialManagerEventType::UsersAddedToSocialGraph。 ユーザーが読み込まれるとトリガーされます。

リストからソーシャル ユーザー グループを更新しています

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

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

• XblSocialManagerDoWork
• XblSocialManagerEvent
• XblSocialManagerUpdateSocialUserGroup

返されたイベント

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

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

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

• XblSocialManagerDoWork
• XblSocialManagerEvent

返されたイベント

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

XblSocialManagerEventType::SocialUserGroupLoaded。 ソーシャル ユーザー グループが作成されるとトリガーされます。

XblSocialManagerEventType::UsersAddedToSocialGraph。 ユーザーが読み込まれるとトリガーされます。

XblSocialManagerEventType::UsersRemovedFromSocialGraph。 ユーザーがソーシャル グラフから削除されるとトリガーされます。

XblSocialManagerEventType::PresenceChanged。 ソーシャル グラフでのユーザーのプレゼンスが変化するとトリガーされます。

XblSocialManagerEventType::ProfilesChanged。 ソーシャル グラフでのユーザーのプロフィールが変化するとトリガーされます。

XblSocialManagerEventType::SocialRelationshipsChanged。 ソーシャル グラフでローカル ユーザーと別のユーザーの関係が変化するとトリガーされます。

XblSocialManagerEventType::SocialUserGroupUpdated。 ソーシャル ユーザー グループの更新が完了するとトリガーされます。

その他の詳細

この例では、Social Manager によって提供される追加のコントロールの一部を示します。

ゲーム ループの間、ソーシャル ユーザー グループ フィルターに依拠して最新のユーザー リストを取得する代わりに、ゲーム ループの外側でソーシャル グラフを初期化します。 次に、タイトルは XblSocialManagerDoWork 関数によって返された イベント に依存します。

イベント は 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