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

# 社交管理員概觀

> XBOX 服務社交管理員 API 如何簡化社交關係圖，使用即時活動讓好友和線上狀態資料透過同步呼叫保持最新。

本主題說明 XBOX 服務社交管理員 API 如何簡化追蹤線上好友及其遊戲活動的工作。

XBOX 服務提供豐富的社交關係圖，遊戲可以將其用於各種案例。
使用 XBOX 服務 API (XSAPI) 中的社交 API 來取得和維護社交關係圖的相關資訊相當複雜。要讓這些資訊保持最新可能很麻煩。
如果沒有正確執行此動作，可能會導致效能問題、資料過時，或因為呼叫 XBOX 服務社交服務的頻率超過必要而遭到節流。

社交管理員透過下列方式解決此問題：

* 建立簡單易於呼叫的 API。
* 在背景使用即時活動 (RTA) 服務來建立最新的資訊。
* 開發人員可以同步呼叫社交管理員 API，而不會對服務造成任何額外負擔。

社交管理員隱藏了處理多個 RTA 訂閱和重新整理使用者資料的複雜性，讓開發人員可以輕鬆取得想要的最新關係圖，進而創造出有趣的案例。

如需詳細資訊，請參閱[社交管理員記憶體和效能](https://docs.xbox.com/zh-TW/services/xbox-services/community/social-manager/concepts/live-socmgr-mem-perf.md)。

## 功能

社交管理員提供下列功能。

* 簡化的社交 API
* 最新的社交關係圖
* 控制所顯示資訊的詳細程度
* 減少對 XBOX 服務的呼叫次數
  * 這直接關係到資料擷取整體延遲的降低
* 安全執行緒
* 有效率地讓資料保持最新

## 核心概念

**社交關係圖**：系統會為裝置上的本機使用者建立*社交關係圖*。
這會建立一個結構，讓使用者所有好友的相關資訊保持最新。

> [!NOTE]
>
> 在 Windows 上，只能有一個本機使用者。

**XBOX 社交使用者**：*XBOX 社交使用者*是與群組中某位使用者相關聯的一整組社交資料。

**XBOX 社交使用者群組**：群組是使用者的集合，用於填入 UI 等用途。
群組有兩種類型：

* **篩選群組**：*篩選群組*會取得本機 (呼叫端) 使用者的*社交關係圖*，並根據指定的篩選參數傳回一組持續保持最新的使用者。

* **清單群組**：*清單群組*會取得使用者清單，並傳回這些使用者持續保持最新的檢視。這些使用者可以位於使用者的好友清單之外。

若要讓*社交使用者群組*保持最新，必須在每個畫面呼叫 [XblSocialManagerDoWork](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork.md) 函式。

## API 概觀

您最常使用的是下列主要 API。

### 將本機使用者新增至社交管理員

* 平面 C API 函式：[XblSocialManagerAddLocalUser](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanageraddlocaluser.md)

將本機使用者新增至社交管理員會為該使用者建立*社交關係圖*。
新增本機使用者之後，就可以為該使用者建立*社交使用者群組*。

社交管理員會讓 XBOX 社交使用者群組保持最新，並可依線上狀態或與使用者的關係篩選使用者群組。
例如，可以建立一個 XBOX 社交使用者群組，其中包含使用者所有在線上且正在玩目前遊戲的好友。
當好友開始或停止玩遊戲時，此群組會保持最新。

### XBOX 社交使用者群組

* 平面 C API 函式：[XblSocialManagerAddLocalUser](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanageraddlocaluser.md)

XBOX 社交使用者群組是符合特定準則的使用者群組，如先前所述。
XBOX 社交使用者群組會公開其群組類型、正在追蹤哪些使用者或套用了哪些篩選條件，以及該群組所屬的本機使用者。

您可以在 [XBOX Live API 參考](https://aka.ms/xboxliveuwpdocs)中找到社交管理員 API 的完整描述。
您也可以在 `XblSocialManager` 前置詞文件中找到這些 API。

## 使用方式

### 從篩選條件建立社交使用者群組

在此案例中，您想要從篩選條件取得使用者清單，例如使用者的好友清單，或使用者標記為最愛的好友子集。

**平面 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](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblpresencefilter.md)
* [XblRelationshipFilter](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblrelationshipfilter.md)
* [XblSocialManagerAddLocalUser](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanageraddlocaluser.md)
* [XblSocialManagerCreateSocialUserGroupFromFilters](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagercreatesocialusergroupfromfilters.md)
* [XblSocialManagerDoWork](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork.md)
* [XblSocialManagerEvent](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent.md)

#### 傳回的事件

**已新增本機使用者**：在使用者社交關係圖載入完成時觸發。指出初始化期間是否發生任何錯誤。

* 平面 C API：[XblSocialManagerEventType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype.md)`::LocalUserAdded`

**已載入社交使用者群組**：在建立社交使用者群組時觸發。

* 平面 C API：[XblSocialManagerEventType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype.md)`::SocialUserGroupLoaded`

**已將使用者新增至社交關係圖**：在載入使用者時觸發。

* 平面 C API：[XblSocialManagerEventType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype.md)`::UsersAddedToSocialGraph`

如需詳細資訊，請參閱下列內容：

* [XblSocialManagerEventType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype.md) (平面 C API)

#### 其他詳細資料

**平面 C API**
上一個範例示範如何為使用者初始化社交管理員、為該使用者建立社交使用者群組，並讓其保持最新。

篩選選項為 [XblPresenceFilter](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblpresencefilter.md) 和 [XblRelationshipFilter](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblrelationshipfilter.md) 列舉。

在遊戲迴圈中，[XblSocialManagerDoWork](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork.md) 函式會以該群組中使用者的最新快照更新所有已建立的檢視。

您可以呼叫 [XblSocialManagerUserGroupGetUsers](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerusergroupgetusers.md) 函式來取得檢視中的使用者。它會傳回 `XblSocialManagerUserPtrArray`，這是 XSAPI 所擁有之 [XblSocialManagerUser](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanageruser.md) 物件的陣列。
[XblSocialManagerUser](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanageruser.md) 包含玩家代號、玩家圖片和 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](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanageraddlocaluser.md)
* [XblSocialManagerCreateSocialUserGroupFromList](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagercreatesocialusergroupfromlist.md)
* [XblSocialManagerDoWork](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork.md)
* [XblSocialManagerEvent](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent.md)

#### 傳回的事件

[XblSocialManagerEventType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype.md)`::LocalUserAdded`。在使用者社交關係圖載入完成時觸發。指出初始化期間是否發生任何錯誤。

[XblSocialManagerEventType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype.md)`::SocialUserGroupLoaded`。在建立社交使用者群組，且已將追蹤的使用者新增至社交關係圖時觸發。

[XblSocialManagerEventType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype.md)`::UsersAddedToSocialGraph`。在載入使用者時觸發。

### 從清單更新社交使用者群組

您也可以呼叫 [XblSocialManagerUpdateSocialUserGroup](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerupdatesocialusergroup.md)，變更社交使用者群組中追蹤的使用者清單。

**平面 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](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork.md)
* [XblSocialManagerEvent](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent.md)
* [XblSocialManagerUpdateSocialUserGroup](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerupdatesocialusergroup.md)

#### 傳回的事件

**已更新社交使用者群組**：在社交使用者群組更新完成時觸發。

* C++：`social_user_group_updated`
* C：[XblSocialManagerEventType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype.md)::SocialUserGroupUpdated

**已將使用者新增至社交關係圖**：在載入使用者時觸發。如果透過清單新增的使用者已經在關係圖中，就不會觸發此事件。

* C++：`users_added_to_social_graph`
* C：[XblSocialManagerEventType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype.md)::UsersAddedToSocialGraph

**已從社交關係圖移除使用者**：在先前的使用者從社交關係圖中移除時觸發。

* C：[XblSocialManagerEventType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype.md)::UsersRemovedFromSocialGraph

### 使用社交管理員事件

社交管理員會以事件的形式告訴您發生了什麼事。
您可以使用這些事件來更新 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](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork.md)
* [XblSocialManagerEvent](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent.md)

#### 傳回的事件

[XblSocialManagerEventType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype.md)`::LocalUserAdded`。在使用者社交關係圖載入完成時觸發。指出初始化期間是否發生任何錯誤。

[XblSocialManagerEventType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype.md)`::SocialUserGroupLoaded`。在建立社交使用者群組時觸發。

[XblSocialManagerEventType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype.md)`::UsersAddedToSocialGraph`。在載入使用者時觸發。

[XblSocialManagerEventType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype.md)`::UsersRemovedFromSocialGraph`。在使用者從社交關係圖中移除時觸發。

[XblSocialManagerEventType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype.md)`::PresenceChanged`。在社交關係圖中使用者的線上狀態變更時觸發。

[XblSocialManagerEventType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype.md)`::ProfilesChanged`。在社交關係圖中使用者的個人檔案變更時觸發。

[XblSocialManagerEventType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype.md)`::SocialRelationshipsChanged`。在本機使用者與社交關係圖中另一位使用者之間的關係變更時觸發。

[XblSocialManagerEventType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype.md)`::SocialUserGroupUpdated`。在社交使用者群組的更新完成時觸發。

#### 其他詳細資料

此範例示範社交管理員提供的一些額外控制。

社交關係圖是在遊戲迴圈之外初始化，而不是依賴社交使用者群組篩選條件在遊戲迴圈期間提供最新的使用者清單。
接著，遊戲會依賴 [XblSocialManagerDoWork](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork.md) 函式所傳回的*事件*。

*事件*是 [XblSocialManagerEvent](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent.md) 的清單。每個 [XblSocialManagerEvent](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent.md) 都包含在上一個畫面期間發生的社交關係圖變更。
例如，[XblSocialManagerEventType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype.md)`::ProfilesChanged` 和 [XblSocialManagerEventType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype.md)`::UsersAddedToSocialGraph`。

如需詳細資訊，請參閱 [XblSocialManagerEvent](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent.md) API 文件。

### 清除

#### 清除社交使用者群組

下列範例會清除已建立的社交使用者群組。
呼叫端也應該移除其對任何已建立之社交使用者群組的參考，因為它現在已無效。

**平面 C API**

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

如需詳細資訊，請參閱下列內容：

* [XblSocialManagerDestroySocialUserGroup](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdestroysocialusergroup.md)

#### 清除本機使用者

如下列範例所示，移除本機使用者會移除已載入之使用者的社交關係圖，以及使用該使用者建立的任何社交使用者群組。

使用平面 C API 時，將不會再收到已移除使用者的任何事件。

**平面 C API**

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

如需詳細資訊，請參閱下列內容：

* [XblSocialManagerRemoveLocalUser](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerremovelocaluser.md)


## Related topics

- [社交管理員 (內容)](https://docs.xbox.com/zh-TW/services/xbox-services/community/social-manager/live-social-manager-nav.md)
- [社交功能概觀](https://docs.xbox.com/zh-TW/services/xbox-services/community/live-social-overview.md)
- [取得社交關係](https://docs.xbox.com/zh-TW/services/xbox-services/community/people-system/how-to/live-getting-a-social-relationship.md)
- [社交管理員概念 (內容)](https://docs.xbox.com/zh-TW/services/xbox-services/community/social-manager/concepts/live-socmgr-concepts-nav.md)
- [社交管理員](https://docs.xbox.com/zh-TW/services/xbox-services/community/social-manager/index.md)