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

# Social Manager 概述

> XBOX 服务 Social Manager API 如何简化社交图，使用实时活动保持朋友和状态数据最新，并支持同步调用。

本主题描述 XBOX 服务 Social Manager API 如何简化跟踪在线朋友及其游戏活动。

XBOX 服务提供了丰富的社交图，游戏可以将其用于各种场景。
使用 XBOX Services API (XSAPI) 中的社交 API 来获取和维护有关社交图的信息很复杂。使这些信息保持最新可能很复杂。
如果操作不当，可能会导致性能问题、数据陈旧或因调用 XBOX 服务的社交服务的频率高于必要频率而被限制。

Social Manager 通过以下方式解决此问题：

* 创建简单易用的 API。
* 通过在后台使用实时活动 (RTA) 服务来创建最新的信息。
* 开发者可以同步调用 Social Manager API，而不会对服务造成任何额外的压力。

Social Manager 屏蔽了处理多个 RTA 订阅以及为用户刷新数据的复杂性，让开发者可以轻松获取他们想要的最新图，从而创建有趣的场景。

有关详细信息，请参阅 [Social Manager 内存和性能](/services/xbox-services/community/social-manager/concepts/live-socmgr-mem-perf)。

## 功能

Social Manager 提供以下功能。

* 简化的社交 API
* 最新的社交图
* 控制显示信息的详细程度
* 减少对 XBOX 服务的调用次数
  * 这与数据获取的总体延迟降低直接相关
* 线程安全
* 高效地保持数据最新

## 核心概念

**社交图**：为设备上的本地用户创建*社交图*。
这将创建一个结构，用于保持用户所有朋友的信息处于最新状态。

<Note>在 Windows 上，只能有一个本地用户。</Note>

**XBOX 社交用户**：*XBOX 社交用户*是与来自组的用户关联的完整社交数据集。

**XBOX 社交用户组**：组是一组用户，用于填充 UI 等。
有两种类型的组：

* **过滤组**：*过滤组*采用本地（调用）用户的*社交图*，并根据指定的过滤参数返回持续保持最新的用户集。

* **列表组**：*列表组*采用用户列表并返回这些用户的一致最新视图。这些用户可以在用户的朋友列表之外。

要使*社交用户组*保持最新，必须每帧调用 [XblSocialManagerDoWork](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork) 函数。

## API 概述

您最常使用以下关键 API。

### 将本地用户添加到 Social Manager

* Flat C API 函数：[XblSocialManagerAddLocalUser](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanageraddlocaluser)

将本地用户添加到 Social Manager 会为该用户创建一个*社交图*。
添加本地用户后，可以为该用户创建*社交用户组*。

Social Manager 将保持 XBOX 社交用户组的最新状态，并可以按用户的状态或关系过滤用户组。
例如，可以创建一个包含所有正在线并玩当前游戏的用户朋友的 XBOX 社交用户组。
随着朋友开始或停止玩游戏，该组将保持最新。

### XBOX 社交用户组

* Flat C API 函数：[XblSocialManagerAddLocalUser](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanageraddlocaluser)

XBOX 社交用户组是一组满足特定条件的用户，如前所述。
XBOX 社交用户组公开它们是什么类型的组、正在跟踪哪些用户或对它们设置了什么过滤器，以及该组所属的本地用户。

您可以在 [XBOX Live API 参考](https://aka.ms/xboxliveuwpdocs)中找到 Social Manager API 的完整描述。
您还可以在 `XblSocialManager` 前缀文档中找到这些 API。

## 用法

### 从过滤器创建社交用户组

在此场景中，您想要来自过滤器的用户列表，例如用户的朋友列表或用户标记为收藏的朋友子集。

**Flat 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)

#### 返回的事件

**已添加本地用户**：在完成用户社交图加载时触发。指示初始化期间是否发生任何错误。

* Flat C API：[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::LocalUserAdded`

**已加载社交用户组**：在创建社交用户组时触发。

* Flat C API：[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::SocialUserGroupLoaded`

**已将用户添加到社交图**：在加载用户时触发。

* Flat C API：[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::UsersAddedToSocialGraph`

有关详细信息，请参阅以下内容：

* [XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)（Flat C API）

#### 其他详细信息

**Flat 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) 函数获取视图中的用户。它返回 `XblSocialManagerUserPtrArray`，即由 XSAPI 拥有的 [XblSocialManagerUser](/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanageruser) 对象数组。
[XblSocialManagerUser](/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanageruser) 包含诸如玩家代号、玩家图片和 URI 等社交信息。

### 从列表创建和更新社交用户组

在此场景中，您需要用户列表的社交信息，例如多人游戏会话中的用户。

**Flat 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) 来更改社交用户组中跟踪的用户列表。

**Flat 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 或执行其他逻辑。

**Flat 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 文档。

### 清理

#### 清理社交用户组

以下示例清理已创建的社交用户组。
调用方还应删除对任何已创建的社交用户组的所有引用，因为它现在无效。

**Flat 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)

#### 清理本地用户

如以下示例所示，删除本地用户会删除已加载用户的社交图以及使用该用户创建的任何社交用户组。

使用 Flat C API 时，不会再收到已删除用户的更多事件。

**Flat C API**

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

有关详细信息，请参阅以下内容：

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


## Related topics

- [Social Manager](/zh-CN/services/xbox-services/community/social-manager/live-social-manager-nav.md)
- [社交功能概述](/zh-CN/services/xbox-services/community/live-social-overview.md)
- [获取社交关系](/zh-CN/services/xbox-services/community/people-system/how-to/live-getting-a-social-relationship.md)
- [Multiplayer Manager 概述](/zh-CN/services/xbox-services/multiplayer/mpm/live-multiplayer-manager-overview.md)
- [Multiplayer Manager API 概述](/zh-CN/services/xbox-services/multiplayer/mpm/concepts/live-multiplayer-manager-api-overview.md)