社交管理器概述

项目
05/09/2023

本主题介绍 Xbox 服务社交管理器 API 如何简化在线好友及其游戏活动的跟踪。

Xbox 服务提供了丰富的社交图片，游戏可用于各种方案。使用 Xbox 服务 API （XSAPI）中的社交 API 来获取和维护有关社交图形的信息很复杂。使此信息保持最新可能很复杂。如果未正确执行此操作，可能会导致性能问题、过时数据或受到限制，因为 Xbox 服务社交服务的调用频率高于需要。

社交管理器通过执行以下操作来解决此问题：

创建简单的 API 调用。
在后台使用实时活动（RTA）服务创建最新信息。
开发者可以同步调用社交管理器 API，不会为服务带来任何额外负担。

社交管理器可以掩盖处理多个 RTA 订阅的复杂性，并为用户刷新数据，并使开发人员能够轻松获取所需的最新图形，从而创建有趣的方案。

有关详细信息，请参阅社交管理器内存和性能。

功能

社交管理器提供以下功能。

简化的社交 API
最新的社交图片
控制显示信息的详细级别
减少调用 Xbox 服务的次数
- 这与数据获取的总体延迟减少直接相关
安全线程
有效地使数据保持最新

核心概念

社交图片：社交图片为设备上的本地用户创建。这将创建一个结构，该结构可令用户好友的所有相关信息保持最新。

注意

在 Windows 上只能有一个本地用户。

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

Xbox 社交用户组：组是用于诸如填充 UI 这样的操作的用户集合。组有两种类型：

筛选器组：筛选器组 采用本地（调用）用户的 社交图 ，并基于指定的筛选器参数返回一组一致的全新用户。
列表组：列表组获取用户列表，并返回这些用户的始终最新的视图。这些用户可能不在用户好友列表中。

为使社交用户组保持最新状态，则必须每隔一定时间调用 XblSocialManagerDoWork 函数。

API 概述

最常用的是以下关键 API。

平面 C API 函数：XblSocialManagerAddLocalUser

向社交管理器添加本地用户，会为该用户创建社交图片。添加本地用户后，可为该用户创建社交用户组。

社交管理器会将 Xbox 社交用户组保持最新，并可以按状态或用户关系筛选用户组。例如，可能会创建包含所有在线并且正在玩当前游戏的用户好友的 Xbox 社交用户组。这会在好友开始或停止玩游戏时保持最新。

平面 C API 函数：XblSocialManagerAddLocalUser

Xbox 社交用户组是满足特定条件的用户组，如前所述。 Xbox 社交用户组显示它们是哪类组，在跟踪哪些用户或它们的筛选器设置，以及组所属的本地用户。

可在 Xbox Live API 参考中找到社交管理器 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.
        }
    }
}

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

返回的事件

已添加本地用户：在用户社交图片加载完毕时触发。将指示初始化过程中是否发生了任何错误。

平面 C API：XblSocialManagerEventType::LocalUserAdded

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

平面 C API：XblSocialManagerEventType::SocialUserGroupLoaded

已将用户添加到社交图片 - 在载入用户后触发。

平面 C API：XblSocialManagerEventType::UsersAddedToSocialGraph

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

XblSocialManagerEventType (flat C API)

其他详细信息

平面 C API 上述示例演示了如何为用户初始化社交管理器，以及如何为该用户创建社交用户组并使其保持最新状态。

可在 XblPresenceFilter 和 XblRelationshipFilter 枚举中筛选选项。

在游戏循环中，XblSocialManagerDoWork 函数会使用该组中用户的最新快照更新已创建的所有视图。

可以通过调用 XblSocialManagerUserGroupGetUsers 函数来获取视图中的用户。它返回一个 XblSocialManagerUserPtrArray，即 XSAPI 拥有的 XblSocialManagerUser 对象数组。 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
        }
    }
}

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

返回的事件

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

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

返回的事件

已更新社交用户组：在社交用户组更新完毕后触发。

C++：social_user_group_updated
C：XblSocialManagerEventType::SocialUserGroupUpdated

已将用户添加到社交图片 - 在载入用户后触发。如果通过列表添加的用户已在图中，则不会触发此事件。

C++：users_added_to_social_graph
C：XblSocialManagerEventType::UsersAddedToSocialGraph

已从社交图片中删除用户：从社交图片中删除以前的用户时触发。

C：XblSocialManagerEventType::UsersRemovedFromSocialGraph

社交管理器会以事件形式告诉您所发生的事情。您可以使用这些事件来更新 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。当社交用户组的更新完成时触发。

其他详细信息

此示例演示社交管理器提供的一些附加控件。

与依靠社交用户组筛选器在游戏循环中提供新用户列表不同，社交图片在游戏循环外初始化。然后，游戏依赖于 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

通过

功能

核心概念

API 概述

将本地用户添加到社交管理器

Xbox 社交用户组

使用

从筛选器创建社交用户组

返回的事件

其他详细信息

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

返回的事件

从列表更新社交用户组

返回的事件

使用社交管理器事件

返回的事件

其他详细信息

清理

清除社交用户组

清除本地用户

其他资源