客户端使用 Xbox 服务用户权限

可使用本主题来检查和解决 Xbox 服务上可用的用户权限问题，并确定 Xbox 主机或 Windows 电脑上的追加销售系统。

目录

• 先决条件
• 客户端处理以及用户对权限和追加销售的体验
• 应用端权限处理的最佳做法
• 在你的应用中测试基于权限的访问控制
• 要检查的权限 ID

先决条件

为了处理 Xbox 服务客户端应用中的用户权限，需要配置游戏以便向 Xbox 服务进行身份验证。 有关详细信息，请参阅身份验证和登录概述以及 Xbox 服务用户权限概述。

客户端处理以及用户对权限和追加销售的体验

客户端应用受“Xbox 要求 (XR)”的限制，需要具有控制游戏部分内容的权限，例如 XR-045：Xbox 服务和帐户权限。 有关详细信息，请参阅策略和 Xbox 要求。

对于受权限控制的应用，可以使用 API。 XUserCheckPrivilege 决定用户是否具有某个特定权限。 XUserResolvePrivilegeWithUiAsync 显示所需用户权限的解决 UI。 如果用户没有权限，将显示需要说明或追加销售的必要 UI。

例如，对于设有 XPRIVILEGE_MULTIPLAYER_SESSIONS 权限要求的应用，需要完成以下流程。

1. 用户会看到一个用于启动多人游戏会话的选项，并尝试通过选择 UI 中的相应选项来开始匹配。
2. 应用会使用 XUserCheckPrivilege API 检查“提示”。
   • 如果存在，则假定用户具有权限并进行处理。
   • 如果不存在，则转到下一步。

   注意

   当由于 XToken 中缺少特权而拒绝访问某个功能时，Xbox 服务 API 返回状态代码 403 (HTTP_E_STATUS_FORBIDDEN) 。 Xbox 服务的所有终结点都根据需要强制实施基于权限的访问控制。

3. 为响应失败代码，游戏应用随后将使用你正尝试解决的权限的相应权限 ID 调用 XUserResolvePrivilegeWithUiAsync。 此函数调用 Xbox 服务以查看用户是否具有权限，然后告知用户操作失败的原因或向用户显示用于解决问题的 UI。 此 API 调用可能会导致以下结果。
   • 显示与 Xbox 服务策略和强制审阅方颁发的用户强制状态相关的 UI。
   • 显示与他们的家长控制相关的 UI。
   • 提升适用的订阅服务，如 Xbox Live Gold 订阅。
   • 将结果返回到游戏（成功或失败，并包含原因）。

   注意

   如果无法访问 Xbox 服务或网络， XUserResolvePrivilegeWithUiAsync 则失败。 应将此次失败视为用户不具备权限。

4. 从 XUserResolvePrivilegeWithUiAsync 返回时：
   1. 如果返回了失败，则因为（例如）用户的封禁可能会失效或家长控制可能会更改等，游戏应允许用户继续点击按钮。
   2. 如果返回了成功，则表示已对用户采取补救措施，并且游戏可能会再次尝试该操作。 作为 XUserResolvePrivilegeWithUiAsync 执行的补救措施的一部分，用户的令牌将包含所需的权限。

注意

特权是宏级检查，用于回答“我可以吗？”例如，“此用户是否可以访问多人游戏功能？”但是，权限并不是应用必须检查的唯一权限。

有关适用于你游戏的权限的详细信息，请参阅策略和 Xbox 要求主题中的 XR-015。

示例代码

使用以下代码示例确保在访问游戏中的多人游戏功能之前检查用户的多人游戏权限。

XUserPrivilegeDenyReason reason;
bool hasPrivilege = false;

// check the Multiplayer (254) privilege
HRESULT hr = XUserCheckPrivilege(userHandle, XUserPrivilegeOptions::None, XUserPrivilege::Multiplayer, &hasPrivilege, &reason);

// error with the user such that we can't yet check privileges
if(E_GAMEUSER_RESOLVE_USER_ISSUE_REQUIRED == hr)
{
      asyncBlock.callback = [](XAsyncBlock *async)
      {
         HRESULT hr = XUserResolveIssueWithUiResult(async);
         // if SUCCEEDED(hr), the issue is resolved, try the privilege check again
         // if FAILED(hr), the issue is not resolved, the title should deny access to the user, and perhaps try again later
      };

      hr = XUserResolveIssueWithUiAsync(userHandle, nullptr, &asyncBlock);
}

// user doesn't have the requested privilege, try to resolve the issue
else if(!hasPrivilege)
{
      asyncBlock.callback = [](XAsyncBlock *async)
      {
         HRESULT hr = XUserResolvePrivilegeWithUiResult(async);
         // if SUCCEEDED(hr), all privilege issues are now resolved, the user has the privilege,
         //    and the title should continue. It is not necessary to call XUserCheckPrivilege again.
         // if FAILED(hr), the user did not resolve all privileges, the title should deny access to the user and perhaps try again later
      };

      hr = XUserResolvePrivilegeWithUiAsync(userHandle, XUserPrivilegeOptions::None, XUserPrivilege::Multiplayer, &asyncBlock);
}
else if(hasPrivilege)
{
      // the user has the privilege, continue!
}

应用端权限处理的最佳做法

处理游戏中的用户权限时，请确保采用以下最佳做法。

解决应用中权限的频率

对于权限检查，要求是确保在每次为用户启动应用时，用户具有适当权限，并解决权限问题。 建议检查每个逻辑会话和离散操作。

会话定义可能因应用的使用情况而异。

以下是一些最佳做法示例。

• 对于媒体流应用（如视频播放器），每选择一次“播放”按钮（流开始）或在播放列表启动（对于多个流，如音乐播放列表）时，解决权限检查一次。
• 对于消息发送应用，为发送的第一条消息检查一次权限。
• 对于使用第三方匹配服务的多人游戏应用，每个会话（匹配）启动时解决权限检查。

从不对用户的订阅级别作出任何假定

在过去，Xbox 360 中的声明提供了有关用户订阅级别的信息 (如 Xbox Live Gold 状态)。 此声明已弃用，引入了 Xbox One 家族和更高版本。 确保使用权限做出决策。 用户的级别或用户获取权限的方式对应用而言应该是不透明的。

离线模式

如果 XUserCheckPrivilege 返回的结果为服务已关闭或不可访问，则将此结果视为权限检查已返回了失败。 通过执行此操作，你的应用可进行故障防范，保持与 XR 兼容。

目标是正确的用户

如果权限检查未指定其他用户，则建议始终引用代理用户。 如果应用支持指定用户，则应使用当前指定的用户。

例如，有三个已登录的用户：Bill、Bob 和 Beth。 应用支持在“活动用户”之间进行切换，以便指定要使用的建议、历史记录和设置。 Beth 启动了你的应用。 当应用运行时，活动用户切换为 Bob。 Bob 具有单独的配置文件、一组建议和历史记录。 致电 XUserCheckPrivilege 启动 Bob 的权限检查。

不通过 UI 检查或失去焦点通过 UI 检查

有些情况下，应用无法呈现模式，因此会阻止权限检查的 UX。 例如，应用在后台播放音乐或者当 Skype 应用在后台运行时有来电。 但是，应用必须仍可检查权限。 我们建议调用 XUserCheckPrivilege。 XUserCheckPrivilege 返回用户的当前权限状态，或返回适用的故障，而不是显示 UI。 如用户权限所定义，你的应用可能会影响用户，并在应用重新聚焦时提示用户进行权限检查。

相反，游戏可能会显示用户非模式错误信息或其他 UX（如果需要）。 如果应向用户显示具有阻止作用的 UX，可以再次调用 XUserResolvePrivilegeWithUiAsync 以显示正确的 UX–如追加销售或强制状态。

在你的应用中测试基于权限的访问控制

权限基于以下输入进行计算。

• 用户的有效订阅权利
• 设备的有效权限权利
• 客户端平台的有效特权权利-
• 当前游戏的有效权限权利
  • 可以使用一组权限来打包游戏，以便应用的所有用户都能在正在运行的应用中自动获取这些权限来使用。 如果你的游戏需要此功能，请与 Microsoft 帐户管理员联系。
• 借助家长控制，家长可决定在家庭成员中添加或删除儿童所需的权限
• Xbox 审查方可能会封禁已确定为滥用服务的用户或设备的权限

管理和检查用户特权和权限

可以通过两种方式访问用户隐私设置。

• 在电脑上：
  转到 https://aka.ms/XboxPrivSettings。
• 在 Xbox 上：
  转到设置 -> 常规 -> 在线安全 & 家庭 -> 隐私 & 在线安全 -> Xbox 隐私

使用 XUserCheckPrivilege 检查的特权

XUserPrivilege::CrossPlay

• 说明: 允许用户在以下情况中与未登录到 Xbox 服务的其他真实玩家一同参与游戏会话: 同一会话中的同步玩家对玩家游戏、异步的回合制游戏、基于团队的游戏、用户启动的匹配、发送或接受邀请、加入正在进行的会话。
• 要求：XR-045–Xbox 服务和帐户特权
• 特权 ID:185
• 电脑上的设置: 可以与 Xbox 服务之外的人一起玩游戏
• Xbox 上的设置: 可以加入跨网络游戏

XUserPrivilege::Sessions

• 说明: 允许用户在共享环境中或在游戏是混合免费游戏和付费多人游戏的情况下参与连接的单玩家体验，并使用此特权封闭这些 Xbox 主机体验。 单玩家体验不得具有权限 252 或 254（分别是通信和多人游戏）所涵盖的任何功能。 对此权限的使用是一项要求平台许可的游戏功能。
• 要求：XR-045–Xbox 服务和帐户特权
• 特权 ID:189
• 电脑上的设置: 可以加入多人游戏
• Xbox 上的设置: 可以加入多人游戏

XUserPrivilege::Multiplayer

• 说明: 允许用户在以下情况中与真实用户(非机器人)一同加入在线多人游戏会话: 同一会话中的同步玩家对玩家游戏、异步的回合制游戏、基于团队的游戏、用户启动的匹配、发送或接受邀请、加入正在进行的会话。 请注意，此权限与在同一设备上运行的本地多人游戏无关。
• 要求：XR-045–Xbox 服务和帐户特权
• 特权 ID: 254
• 电脑上的设置: 可以加入多人游戏
• Xbox 上的设置: 可以加入多人游戏

XUserPrivilege::UserGeneratedContent

• 说明: 允许用户在线查看其他用户的 UGC、下载其他用户的 UGC 或者在线共享自己的 UGC。 这并不会限制对之前下载的 UGC 的使用。
• 要求：XR-045–Xbox 服务和帐户特权
• 特权 ID: 247
• 电脑上的设置: 可以查看并上传社区创建
• Xbox 上的设置: 可以查看并上传社区创建

XUserPrivilege::SocialNetworkSharing

• 说明: 仅限 Xbox 主机: 允许用户在 Xbox 网络外部共享信息，包括游戏进度、Kinect 生成的内容以及游戏剪辑等。
• 要求：XR-045–Xbox 服务和帐户特权
• 特权 ID: 220
• Xbox 上的设置: 可以在 Xbox 外部共享

XUserPrivilege::Communications

• 说明：允许用户通过语音或文本与任何其他 Xbox 服务用户通信。
• 要求：XR-045–Xbox 服务和帐户特权
• 特权 ID: 252
• 电脑上的设置: 其他人员可以使用语音、文本或邀请进行通信
• Xbox 上的设置: 其他人员可以使用语音、文本或邀请进行通信

使用 XblPrivacyCheckPermissionAsync 检查的权限

当需要针对多个用户检查权限时，游戏还可以使用 XblPrivacyBatchCheckPermissionAsync，当检查针对非 Xbox 服务用户的权限时，游戏还可以使用 XblPrivacyCheckPermissionForAnonymousUserAsync。

XblPermission::CommunicateUsingText

• 说明: 检查用户是否可以向目标用户发送包含文本内容的消息。 如果播放器已静音目标用户，则此值不会更改。 请改用 CommunicateUsingVoice。 如果将 comms 设置为 "仅限朋友"，并且目标不是 "朋友"，则此值将为 false。 如果目标用户阻止了你，则此值将为 false。 例如，如果将 comms 设置为 "已阻止"，则此值将为 false。
• 要求: XR-015 - 管理玩家通信
  • 检查其他 Xbox 服务用户时
    • 电脑上的设置: 其他人员可以使用语音、文本或邀请进行通信
    • Xbox 上的设置: 其他人员可以使用语音、文本或邀请进行通信
  • 检查匿名用户时
    • 电脑上的设置：可以使用语音和文本与 Xbox 服务外部进行通信
    • Xbox 上的设置: 可以在 Xbox 外部使用语音和文本进行通信

XblPermission::CommunicateUsingVoice

• 说明: 检查用户是否可以使用语音与目标用户通信。 如果播放器已静音目标用户，则此操作为 false。
• 要求: XR-015 - 管理玩家通信
  • 检查其他 Xbox 服务用户时
    • 电脑上的设置: 其他人员可以使用语音、文本或邀请进行通信
    • Xbox 上的设置: 其他人员可以使用语音、文本或邀请进行通信
  • 检查匿名用户时
    • 电脑上的设置：可以使用语音和文本与 Xbox 服务外部进行通信
    • Xbox 上的设置: 可以在 Xbox 外部使用语音和文本进行通信

测试订阅提供的权限

使用 合作伙伴中心，可以通过 Xbox Live Gold 订阅创建 测试帐户。 使用这些帐户来测试通过 Xbox Live Gold 订阅提供的权限的权限逻辑。

在开发客户端上，可以使用测试帐户购买其他订阅。

注意

必须将订阅发布到已授权帐户或设备开发沙盒，并且开发客户端上的帐户必须在同一沙盒中处于活动状态。

不能使用通过 合作伙伴中心 创建的 测试帐户 来直接购买零售 Xbox Live Gold 订阅。 相反，你可以购买 Xbox Live Gold 的开发人员特定版本，该版本仅适用于开发方案。

测试由运行游戏提供的权限

若要将应用设置为在用户访问应用时自动颁发权限，请联系 Microsoft 帐户管理员。 测试此方案需要配置应用以进行 Xbox 服务身份验证，然后使用登录的用户运行应用。

测试由家长控制删除的权限

要借助使用家长控制（如 XPRIVILEGE_COMMUNICATIONS）删除的权限测试权限逻辑，请在客户端设备上设置家庭帐户。 家长或监护人可使用该设备限制其家庭中儿童的权限。

用户也可以限制自己帐户的权限。 我们建议使用此方法测试需要限制用户权限的场景。

注意

合作伙伴 中心目前不提供创建测试帐户系列 的方法。

要检查的权限 ID

游戏必须检查以下权限 ID。 有关详细信息，请参阅 XR-045：Xbox 服务和帐户权限。

权限 ID	权限名称	枚举常量	说明
254	XPRIVILEGE_MULTIPLAYER_SESSIONS	XUserPrivilege::Multiplayer	当具有此权限时，用户可以加入游戏的多人游戏会话。
185	XPRIVILEGE_CROSS_PLAY	XUserPrivilege::CrossPlay	用户可参与与未登录 Xbox 服务的其他实际用户之间的游戏会话。 示例场景包括：同一会话中同步的玩家对玩家游戏、不同步的回合制游戏、团队游戏、用户启动的匹配、发送或接受邀请、加入正在进行中的会话。
252	XPRIVILEGE_COMMUNICATIONS	XUserPrivilege::Communications	当具有此权限时，用户可以与任何人进行语音聊天或使用短信功能。 需要额外的隐私权限检查来确定用户有权与谁通信。
189	XPRIVILEGE_SESSIONS	XUserPrivilege::Sessions	用户可参与共享环境中连接的单人游戏体验。 这些体验不得具有权限 252 (XPRIVILEGE_COMMUNICATIONS) 或 254 (XPRIVILEGE_MULTIPLAYER_SESSIONS) 所涵盖的任何功能。 对此权限的使用是一项要求平台许可的游戏功能。
247	XPRIVILEGE_USER_CREATED_CONTENT	XUserPrivilege::UserGeneratedContent	当具有此权限时，用户可以下载并查看在线用户创建的内容。
220	XPRIVILEGE_SOCIAL_NETWORK_SHARING	XUserPrivilege::SocialNetworkSharing	当具有此权限时，用户可以分享有关社交网络的进度信息。

有关可用权限的详细信息，请参阅 XUserPrivilege。

权限计算逻辑

为在主机或其他设备上同时登录的每个用户单独计算权限。 从用户、设备、当前运行的游戏以及平台的有效权利中添加权限。 根据家长控制、 Xbox 服务策略和强制状态以及每个用户的来宾状态，为每个用户删除权限。

有效权利可能来自用户购买的订阅、同时登录的其他用户购买的订阅或直接与设备关联的订阅。 有效权利也可能由促销优惠产生，例如“免费多人游戏周末”活动。

由设备类型产生的权限权利

某些类型的设备 (例如 Xbox One 家族主机和 Xbox 系列主机、Windows 电脑或移动设备) 会自动向从平台连接到 Xbox 服务的任何用户授予权限集合。

由订阅产生的有效权限权利

订阅产品可能会为适用的用户提供一组权限。 以下情景介绍了有效授予用户基于订阅的权限的方式。

• 用户已购买订阅产品。
• 在同一设备上的其他活动用户已购买订阅产品。
• 订阅产品与用户当前正在使用的设备相关联。

从 Xbox One 开始，Xbox Live Gold 订阅遵循此逻辑。 可以将 Xbox Live Gold 订阅关联到设备，在设备上的所有用户都可以有效地获得与 Xbox Live Gold 订阅级别关联的权限。 同时处于活动状态的任何用户（包括发起的来宾）中如有一个用户已购买 Xbox Live Gold 订阅，则他们都可以有效地获得与 Xbox Live Gold 订阅关联的权限。

合作伙伴订阅还可用于向活动用户颁发权限。 此外，仅当特定的参与游戏正在运行时，才可能会颁发与合作伙伴订阅关联的权限。

促销权利

促销权利在有限的时间段内为符合特定动态条件的用户增加权限。 例如，促销可能会在周末期间为某些用户提供多人游戏权限。 诸如“免费 Xbox Live Gold 周末”等历史促销遵循促销权利的模型。

注意

服务和游戏无需直接了解此类促销。 向连接到服务的用户颁发 Xbox 安全令牌服务 (XSTS) 令牌时，会动态计算促销权利的权限。

为发起的来宾帐户删除的权限

发起的来宾是通过 Xbox 服务登录的来宾帐户。 发起的来宾仅存在于客户端设备上有至少一个其他活动用户的情况，例如，仅有一个用户登录的拆分屏幕多人游戏。 这些帐户是经过身份验证的用户，并像任何其他经过身份验证的用户一样获取令牌。 发起的来宾拥有权限，但有些权限不会提供给来宾用户，这种情况不因发起的来宾所拥有的有效权利或当前正在运行的应用而有所改变。

要检查发起的来宾的权限，请调用 XUserCheckPrivilege。 这不会尝试解决。 应该无需显示解决 UI，应该无需调用 XUserResolvePrivilegeWithUiAsync，因为发起的来宾无法被“解决”。 与活动的 Xbox 帐户不同，发起的来宾没有任何路径可进行购买、执行强制操作，也没有一组唯一的权限或限制。

如果用户当前没有登录（这种情况下是“纯来宾”），则不会为该用户颁发任何令牌。 这意味着不会为设备上的任何用户计算有效权限。

XR-045 要求游戏使用 XPRIVILEGE_SOCIAL_NETWORK_SHARING 或 XUserPrivilege::SocialNetworkSharing 检查权限 202。 该权限是为来宾删除的权限之一。

在线安全和 Microsoft 强制措施

Xbox 服务策略和强制审阅方可能会删除不良用户或设备的权限。

家长控制

家长可以删除他们家庭中子女帐户的权限，而不管孩子的订阅或当前运行的游戏是什么。 这通过 Xbox One、Xbox 360 或 Xbox.com 客户端进行控制。

Xbox Live Gold 订阅者权限

特定订阅的权限权利策略是动态的，并且会随着时间的推移而更改。 请记住，即使订阅者有权使用某一权限，但由于家长控制或强制策略的原因，该订阅者可能会失去该权限。

注意

权限并不能精确地反映用户的当前订阅。

XR-045 要求游戏使用 XPRIVILEGE_MULTIPLAYER_SESSIONS 或 XUserPrivilege::Multiplayer 检查权限 254。 这是 Xbox Live Gold 订阅者有权使用的权限之一。

合作伙伴订阅和权限

可以将合作伙伴订阅配置为提供 Xbox 服务权限的集合。 仅当用户登录到已与订阅明确关联的应用时，才会使用合作伙伴订阅来计算用户的权限。

要设置合作伙伴订阅，请联系 Microsoft 帐户管理员。

合作伙伴订阅可以在开发沙盒中进行测试，然后再发布。 只有已获授权可以使用这些开发沙盒的用户和设备才能购买这些订阅。

免费玩 (F2P) 游戏和多人游戏特权

对于专门配置为在免费游戏 (F2P) 模型中运行的游戏，应像往常一样检查 XPRIVILEGE_MULTIPLAYER_SESSIONS / XUserPrivilege::Multiplayer 特权。 但是，通过此设置，无论用户是否拥有 Xbox Live Gold 订阅，用户都将拥有多人游戏权限。 仅当用户被禁用/阻止或以某种方式受到年龄限制时，才会拒绝此权限。 对此权限的使用是一项要求平台许可的游戏功能。 请与 Microsoft 经理或 DPM 协作，为游戏启用此功能。

混合游戏和多人游戏特权

对于专门配置为在混合模型中运行的游戏（即，包含需要付费订阅的多人游戏方案，但也包含可免费播放的方案）的游戏，特权检查过程略有不同。

对于需要付费订阅的内容，应检查 XPRIVILEGE_MULTIPLAYER_SESSIONS / XUserPrivilege::Multiplayer 权限。 但是，对于免费多人游戏方案，应改为检查 XPRIVILEGE_SESSIONS / XUserPrivilege::Sessions 权限。 仅当用户被禁用/阻止或以某种方式受到年龄限制时，才会拒绝此权限。 出于这些原因，多人游戏权限也将被拒绝，但还需要授予付费订阅。 对此权限的使用是一项要求平台许可的游戏功能。 请与 Microsoft 经理或 DPM 协作，为游戏启用此功能。

另请参阅

策略和 Xbox 要求

XUserCheckPrivilege

XUserPrivilege

XUserPrivilegeDenyReason

XUserPrivilegeOptions