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

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

先决条件

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

客户端处理权限和追加销售的玩家体验

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

对于由特权控制的游戏，可以使用 API。 XUserCheckPrivilege 确定玩家是否具有特定权限。 XUserResolvePrivilegeWithUiAsync 显示用户界面 (UI) ，可帮助玩家解决与指定权限相关的问题。 UI 解释了为什么玩家没有权限。

例如，受特权约束 XPRIVILEGE_MULTIPLAYER_SESSIONS 的游戏具有以。

玩家看到启动多人游戏会话的选项，并尝试通过在 UI 中选择适当的选项来启动比赛。
游戏使用 XUserCheckPrivilege API 检查“提示”。
- 如果存在，则假定玩家具有权限并继续。
- 如果不存在，则转到下一步。
注意

当由于 XToken 中缺少权限，导致对某项功能的访问被拒绝时，Xbox 服务 API 会返回 403 状态代码 (HTTP_E_STATUS_FORBIDDEN)。 Xbox 服务的所有终结点都根据需要强制实施基于权限的访问控制。
为了响应失败代码，游戏随后会使用 XUserResolvePrivilegeWithUiAsync 你尝试解决的权限 ID 调用。此函数调用 Xbox 服务以查看玩家是否具有权限，然后告知玩家作失败的原因或向玩家显示 UI 以解决此问题。此 API 调用可能会导致以下结果。
- 显示与 Xbox 服务策略和强制审查者颁发的玩家强制状态相关的 UI。
- 显示与他们的家长控制相关的 UI。
- 推广适用的订阅服务，例如 Xbox Game Pass Core 订阅。
- 将结果返回给游戏 (成功或失败，原因) 。
注意

如果 Xbox 服务或网络无法访问，则 XUserResolvePrivilegeWithUiAsync 会失败。必须将此失败视为玩家没有权限。
从 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 Game Pass 核心状态) 。此声明已弃用，引入了 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 Game Pass 核心版订阅的测试帐户。使用这些帐户测试通过 Xbox Game Pass 核心订阅提供的权限的权限逻辑。

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

注意

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

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

测试正在运行的游戏提供的特权

如果要将游戏设置为在玩家处于游戏中时自动颁发权限，请联系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 Game Pass Core 订阅遵循此逻辑。可以将 Xbox Game Pass Core 订阅关联到设备，并且设备上的所有用户实际上都有权获得与 Xbox Game Pass 核心订阅层关联的特权。任何同时活跃在具有购买 Xbox Game Pass 核心订阅的玩家设备上的用户（包括赞助来宾）都实际上有权获得与 Xbox Game Pass 核心订阅关联的特权。

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

促销权利

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

注意

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

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

发起的来宾是通过 Xbox 服务登录的来宾帐户。赞助来宾仅在客户端设备上存在至少一个其他活动玩家的情况下存在，例如只有一名玩家登录的分屏多人游戏。这些帐户是经过身份验证的用户，并像任何其他经过身份验证的用户一样获取令牌。赞助的来宾确实具有特权，但无论被赞助的来宾的有效权利或当前正在运行的游戏如何，某些特权都会被扣留给来宾玩家。

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

如果玩家当前未登录 (“纯来宾”) ，则不会为用户颁发令牌。这意味着不会为设备上的任何玩家计算有效特权。

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

在线安全和 Microsoft 强制措施

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

家长控制

家长可以删除他们家庭中子女帐户的权限，而不管孩子的订阅或当前运行的游戏是什么。这是通过 Xbox 主机或 Xbox.com Xbox 家庭设置应用管理的。

Xbox Game Pass Core 订阅者的特权

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

注意

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

XR-045 要求游戏使用 XPRIVILEGE_MULTIPLAYER_SESSIONS或 XUserPrivilege::Multiplayer检查特权 254。这是 Xbox Game Pass 核心版订阅者有权享有的特权之一。

合作伙伴订阅和权限

可以将合作伙伴订阅配置为提供 Xbox 服务权限的集合。合作伙伴订阅仅用于计算玩家登录到已显式关联到订阅的游戏时玩家的权限。

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

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

免费游戏和多人游戏权限

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

混合游戏和多人游戏特权

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

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

另请参阅

策略和 Xbox 要求

XUserCheckPrivilege

XUserPrivilege

XUserPrivilegeDenyReason

XUserPrivilegeOptions

反馈

此页面是否有帮助？

Last updated on 2025-11-07