XBOX 服务用户特权的客户端使用

​

目录

• 先决条件
• 特权和增值销售的客户端处理与玩家体验
• 应用侧特权处理的最佳实践
• 在游戏中测试基于特权的访问控制
• 要检查的特权 ID

​

先决条件

​

特权和增值销售的客户端处理与玩家体验

1. 玩家看到启动多人游戏会话的选项，并通过在 UI 中选择相应的选项来 尝试开始比赛。
2. 游戏使用 XUserCheckPrivilege API 检查”提示”。
   • 如果存在，则假定玩家拥有该特权并继续。
   • 如果不存在，请转到下一步。

   [!NOTE] 当 XToken 中缺少某个特权而导致某项功能的访问被拒绝时，XBOX 服务 API 会返回状态代码 403 (HTTP_E_STATUS_FORBIDDEN)。 XBOX 服务的所有终结点都会按需强制执行基于特权的访问控制。

3. 为响应失败代码，游戏随后使用您尝试解决的特权对应的相应 特权 ID 调用 XUserResolvePrivilegeWithUiAsync。此函数调用 XBOX 服务查看玩家是否拥有该特权， 然后告诉玩家操作失败的原因或向 玩家显示解决问题的 UI。此 API 调用可能会产生以下结果。
   • 显示与玩家的执行状态相关的 UI，该状态是由 XBOX 服务策略和执行审核员发布的。
   • 显示与其家长控制相关的 UI。
   • 推广适用的订阅服务，例如 XBOX Game Pass Essential 订阅。
   • 将结果（成功或失败及原因）返回给游戏。

   [!NOTE] 如果无法访问 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!
}

​

应用侧特权处理的最佳实践

​

应用中解决特权的频率

• 对于媒体流式传输应用，例如视频播放器，每次选择 播放 按钮（流开始）时或播放列表开始时（对于多个流，例如音乐播放列表）解析特权检查。
• 对于消息应用，在发送第一条消息时检查一次特权。
• 对于使用第三方匹配服务的多人游戏，每次会话（比赛）开始时解析特权检查。

​

切勿假定用户的订阅层级

​

离线模式

​

定位正确的玩家

​

无 UI 或 UI 失去焦点时进行检查

​

在游戏中测试基于特权的访问控制

• 玩家的有效订阅权益
• 设备的有效特权权益
• 客户端平台的有效特权权益
• 当前游戏的有效特权权益
  • 可以将游戏与一组特权打包在一起，使所有游戏玩家自动获得这些特权，以便在运行的游戏中使用。如果您的游戏需要此功能，请联系您的 Microsoft 账户经理。
• 家长控制，供家长决定为其家庭中的孩子添加或删除哪些特权
• XBOX 审核员可能会为已被识别为滥用服务的玩家或设备禁止特权

​

管理和检查玩家特权和权限

• 在 PC 上：转到 https://aka.ms/XboxPrivSettings。
• 在 XBOX 上：转到 Settings -> General -> Online safety & family -> Privacy & online safety -> XBOX privacy

​

使用 XUserCheckPrivilege 检查的特权

XUserPrivilege::CrossPlay

• 描述：允许玩家在以下场景中与未登录 XBOX 服务的其他真实世界玩家参与游戏会话：同一会话中的同步玩家对玩家游戏、异步回合制游戏、团队游戏、用户发起的匹配、发送或接受邀请、加入正在进行的会话。
• 要求：XR-045 - XBOX 服务和账户特权
• 特权 ID：185
• PC 上的设置：You can play with people outside of XBOX services
• XBOX 上的设置：You can join cross-network play

XUserPrivilege::Sessions

• 描述：允许玩家在共享环境中的互联单人体验中参与，或者在游戏是混合免费游玩和付费多人游戏并使用此特权来控制这些体验的 XBOX 主机场景中。单人体验不得具有特权 252 或 254（分别为通信和多人游戏）所涵盖的任何功能。使用此特权是游戏功能，需要平台批准。
• 要求：XR-045 - XBOX 服务和账户特权
• 特权 ID：189
• PC 上的设置：You can join multiplayer games
• XBOX 上的设置：You can join multiplayer games

XUserPrivilege::Multiplayer

• 描述：允许玩家在以下场景中与真实世界用户（非机器人）加入在线多人游戏会话：同一会话中的同步玩家对玩家游戏、异步回合制游戏、团队游戏、用户发起的匹配、发送或接受邀请、加入正在进行的会话。请注意，此特权不适用于在同一设备上运行的本地多人游戏。
• 要求：XR-045 - XBOX 服务和账户特权
• 特权 ID：254
• PC 上的设置：You can join multiplayer games
• XBOX 上的设置：You can join multiplayer games

XUserPrivilege::UserGeneratedContent

• 描述：允许玩家在线查看其他用户的 UGC、下载其他用户的 UGC 或在线分享他们自己的 UGC。这不限制以前下载的 UGC 的使用。
• 要求：XR-045 - XBOX 服务和账户特权
• 特权 ID：247
• PC 上的设置：You can see and upload community creations
• XBOX 上的设置：You can see and upload community creations

XUserPrivilege::SocialNetworkSharing

• 描述：仅限 XBOX 主机：允许玩家在 XBOX network 之外分享信息，包括游戏进度、Kinect 生成的内容、游戏剪辑等。
• 要求：XR-045 - XBOX 服务和账户特权
• 特权 ID：220
• XBOX 上的设置：You can share outside of XBOX

XUserPrivilege::Communications

• 描述：允许玩家通过语音或文本与任何其他 XBOX 服务用户通信。
• 要求：XR-045 - XBOX 服务和账户特权
• 特权 ID：252
• PC 上的设置：Others can communicate with voice, text or invites
• XBOX 上的设置：Others can communicate with voice, text or invites

​

使用 XblPrivacyCheckPermissionAsync 检查的权限

XblPermission::CommunicateUsingText

• 描述：检查玩家是否可以向目标用户发送包含文本内容的消息。如果玩家已将目标用户静音，此值不会改变。请改用 CommunicateUsingVoice。例如，如果您将通信设置为仅限朋友，而目标不是朋友，则此值将为 false。例如，如果目标玩家已阻止您，则此值将为 false。例如，如果您将通信设置设为已阻止，则此值将为 false。
• 要求：XR-015 - 管理玩家通信
  • 检查其他 XBOX 服务用户时
    • PC 上的设置：Others can communicate with voice, text or invites
    • XBOX 上的设置：Others can communicate with voice, text or invites
  • 检查匿名用户时
    • PC 上的设置：You can communicate outside of XBOX services with voice & text
    • XBOX 上的设置：You can communicate outside of XBOX with voice & text

XblPermission::CommunicateUsingVoice

• 描述：检查玩家是否可以使用语音与目标用户通信。如果玩家已将目标用户静音，则此值将为 false。
• 要求：XR-015 - 管理玩家通信
  • 检查其他 XBOX 服务用户时
    • PC 上的设置：Others can communicate with voice, text or invites
    • XBOX 上的设置：Others can communicate with voice, text or invites
  • 检查匿名用户时
    • PC 上的设置：You can communicate outside of XBOX services with voice & text
    • XBOX 上的设置：You can communicate outside of XBOX with voice & text

​

测试订阅提供的特权

​

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

​

测试被家长控制删除的特权

​

要检查的特权 ID

​

特权计算逻辑

​

由设备类型产生的特权权益

​

由订阅产生的有效特权权益

• 玩家已购买该订阅产品。
• 同一设备上的另一位活跃玩家已购买该订阅产品。
• 该订阅产品与玩家当前使用的设备关联。

​

促销权益

​

为受赞助的访客账户删除的特权

​

在线安全和 Microsoft 执行

​

家长控制

​

XBOX Game Pass Essential 订阅者的特权

​

合作伙伴订阅和特权

​

免费游玩游戏和多人游戏特权

​

混合游戏和多人游戏特权

​

另请参阅