> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ソーシャル マネージャーの概要

> XBOX services Social Manager API が、バックグラウンドで Real-Time Activity を使用してフレンドとプレゼンス データを最新に保ちながら、同期呼び出しでソーシャル グラフを簡素化する方法について説明します。

このトピックでは、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 サブスクリプションを扱う複雑さや、ユーザーのデータをリフレッシュする作業を隠蔽し、開発者が必要な最新のグラフを簡単に取得できるようにすることで、興味深いシナリオを実現します。

詳細については、「[ソーシャル マネージャーのメモリとパフォーマンス](/services/xbox-services/community/social-manager/concepts/live-socmgr-mem-perf)」を参照してください。

## 機能

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

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

## 主要な概念

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

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

**XBOX ソーシャル ユーザー**: *XBOX ソーシャル ユーザー* は、グループ内のユーザーに関連付けられたソーシャル データの完全なセットです。

**XBOX ソーシャル ユーザー グループ**: グループは、UI の生成などに使用されるユーザーの集合です。
グループには 2 つの種類があります:

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

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

*ソーシャル ユーザー グループ* を最新に保つには、[XblSocialManagerDoWork](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork) 関数を毎フレーム呼び出す必要があります。

## API の概要

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

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

* フラット C API 関数: [XblSocialManagerAddLocalUser](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanageraddlocaluser)

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

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

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

* フラット C API 関数: [XblSocialManagerAddLocalUser](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanageraddlocaluser)

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

Social Manager API の完全な説明は [XBOX Live API リファレンス](https://aka.ms/xboxliveuwpdocs) で確認できます。
また、API は `XblSocialManager` プレフィックスのドキュメントでも確認できます。

## 使用方法

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

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

**フラット C API**

```cpp theme={null}
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](/reference/live/xsapi-c/social_manager_c/enums/xblpresencefilter)
* [XblRelationshipFilter](/reference/live/xsapi-c/social_manager_c/enums/xblrelationshipfilter)
* [XblSocialManagerAddLocalUser](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanageraddlocaluser)
* [XblSocialManagerCreateSocialUserGroupFromFilters](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagercreatesocialusergroupfromfilters)
* [XblSocialManagerDoWork](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork)
* [XblSocialManagerEvent](/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent)

#### 返されるイベント

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

* フラット C API: [XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::LocalUserAdded`

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

* フラット C API: [XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::SocialUserGroupLoaded`

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

* フラット C API: [XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::UsersAddedToSocialGraph`

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

* [XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype) (フラット C API)

#### 追加の詳細

**フラット C API**
前の例は、ユーザーに対して Social Manager を初期化し、そのユーザーのソーシャル ユーザー グループを作成し、最新の状態に保つ方法を示しています。

フィルター オプションは [XblPresenceFilter](/reference/live/xsapi-c/social_manager_c/enums/xblpresencefilter) と [XblRelationshipFilter](/reference/live/xsapi-c/social_manager_c/enums/xblrelationshipfilter) の列挙型です。

ゲーム ループ内では、[XblSocialManagerDoWork](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork) 関数が作成されたすべてのビューを、そのグループ内のユーザーの最新のスナップショットで更新します。

ビュー内のユーザーは、[XblSocialManagerUserGroupGetUsers](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerusergroupgetusers) 関数を呼び出すことで取得できます。これは、XSAPI が所有する [XblSocialManagerUser](/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanageruser) オブジェクトの配列である `XblSocialManagerUserPtrArray` を返します。
[XblSocialManagerUser](/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanageruser) には、ゲーマータグ、ゲーマーピック、URI などのソーシャル情報が含まれています。

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

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

**フラット C API**

```cpp theme={null}
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](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanageraddlocaluser)
* [XblSocialManagerCreateSocialUserGroupFromList](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagercreatesocialusergroupfromlist)
* [XblSocialManagerDoWork](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork)
* [XblSocialManagerEvent](/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent)

#### 返されるイベント

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::LocalUserAdded`。ユーザーのソーシャル グラフの読み込みが完了したときにトリガーされます。初期化中にエラーが発生したかどうかを示します。

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::SocialUserGroupLoaded`。ソーシャル ユーザー グループが作成され、追跡ユーザーがソーシャル グラフに追加されたときにトリガーされます。

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::UsersAddedToSocialGraph`。ユーザーが読み込まれるときにトリガーされます。

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

[XblSocialManagerUpdateSocialUserGroup](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerupdatesocialusergroup) を呼び出すことで、ソーシャル ユーザー グループ内の追跡ユーザーのリストを変更することもできます。

**フラット C API**

```cpp theme={null}
// 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](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork)
* [XblSocialManagerEvent](/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent)
* [XblSocialManagerUpdateSocialUserGroup](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerupdatesocialusergroup)

#### 返されるイベント

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

* C++: `social_user_group_updated`
* C: [XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)::SocialUserGroupUpdated

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

* C++: `users_added_to_social_graph`
* C: [XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)::UsersAddedToSocialGraph

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

* C: [XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)::UsersRemovedFromSocialGraph

### Social Manager イベントの使用

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

**フラット C API**

```cpp theme={null}
// 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](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork)
* [XblSocialManagerEvent](/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent)

#### 返されるイベント

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::LocalUserAdded`。ユーザーのソーシャル グラフの読み込みが完了したときにトリガーされます。初期化中にエラーが発生したかどうかを示します。

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::SocialUserGroupLoaded`。ソーシャル ユーザー グループが作成されたときにトリガーされます。

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::UsersAddedToSocialGraph`。ユーザーが読み込まれるときにトリガーされます。

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::UsersRemovedFromSocialGraph`。ユーザーがソーシャル グラフから削除されたときにトリガーされます。

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::PresenceChanged`。ソーシャル グラフ内のユーザーのプレゼンスが変化したときにトリガーされます。

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::ProfilesChanged`。ソーシャル グラフ内のユーザーのプロファイルが変化したときにトリガーされます。

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::SocialRelationshipsChanged`。ローカル ユーザーとソーシャル グラフ内の別のユーザーとの関係が変化したときにトリガーされます。

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::SocialUserGroupUpdated`。ソーシャル ユーザー グループの更新が完了したときにトリガーされます。

#### 追加の詳細

この例は、Social Manager が提供する追加の制御の一部を示しています。

ゲーム ループ中に最新のユーザー リストを提供するためにソーシャル ユーザー グループ フィルターに依存する代わりに、ソーシャル グラフはゲーム ループの外側で初期化されます。
その後、タイトルは [XblSocialManagerDoWork](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork) 関数によって返される *イベント* に依存します。

*Events* は [XblSocialManagerEvent](/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent) のリストです。各 [XblSocialManagerEvent](/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent) には、直前のフレーム中に発生したソーシャル グラフへの変更が含まれています。
たとえば、[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::ProfilesChanged` と [XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::UsersAddedToSocialGraph` などです。

詳細については、[XblSocialManagerEvent](/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent) の API ドキュメントを参照してください。

### クリーンアップ

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

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

**フラット C API**

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

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

* [XblSocialManagerDestroySocialUserGroup](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdestroysocialusergroup)

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

以下の例に示すように、ローカル ユーザーを削除すると、読み込まれたユーザーのソーシャル グラフと、そのユーザーを使って作成されたソーシャル ユーザー グループが削除されます。

フラット C API では、削除されたユーザーに関するイベントはこれ以上受け取りません。

**フラット C API**

```cpp theme={null}
HRESULT hr = XblSocialManagerRemoveLocalUser(user);
```

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

* [XblSocialManagerRemoveLocalUser](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerremovelocaluser)


## Related topics

- [ソーシャル マネージャー](/ja-jp/services/xbox-services/community/social-manager/live-social-manager-nav.md)
- [ソーシャル機能の概要](/ja-jp/services/xbox-services/community/live-social-overview.md)
- [ソーシャル リレーションシップの取得](/ja-jp/services/xbox-services/community/people-system/how-to/live-getting-a-social-relationship.md)
- [ソーシャル マネージャーの概念](/ja-jp/services/xbox-services/community/social-manager/concepts/live-socmgr-concepts-nav.md)
- [ソーシャル マネージャーの特権コード](/ja-jp/services/xbox-services/community/social-manager/concepts/live-socmgr-privilege-codes.md)