XUser 跨平台支持

​

概述

​

集成要求

​

XBOX 主机以及 Windows 上的 Microsoft Store / Game Pass

​

Windows 上的其他商店

• 游戏使用操作系统内置的服务和 UI。
• 安装程序应运行 GamingRepair.exe 以确保 Gaming Runtime Service 已安装。

1. 将该工具包含在你的游戏包中 —— 它随 GDK 附带,位于 [GDK]\bin\GamingRepair.exe。
2. 添加自定义操作 —— 在游戏安装之前运行该工具(例如:start /wait “Installing Gaming Services” GamingRepair.exe scenarioExternal)。这会验证、下载、安装或修复任何缺失的 Gaming Runtime 组件。
3. 处理错误 —— 检查该工具的退出码。如果失败,通知用户并提供手动安装说明。

​

平台差异与统一 API

• 在具有原生支持的平台上(XBOX、Windows) —— XUser 使用操作系统内置的服务进行身份验证、UI 和凭据存储。游戏调用 XUser API,系统会自动处理细节。
• 在没有原生支持的平台上(Steam Deck 等) —— XUser 暴露相同的核心 API,但游戏必须实现事件处理程序以提供必要的 UI(例如为登录显示 QR 码)和数据存储。这让游戏对认证体验拥有完全的控制。

​

新的跨平台功能

​

Remote Connect 身份验证

​

单会话强制(SPoP)

​

使用 Remote Connect 进行跨设备登录

​

工作原理

​

流程

1. 事件处理程序注册 —— 游戏在发起登录之前,使用 XUserPlatformRemoteConnectSetEventHandlers(...) 注册一个 Remote Connect 事件处理程序。游戏提供回调以处理两个关键事件:
   • Show 事件 —— 当 XUser 需要游戏显示一次性代码或 QR 码时触发。处理程序显示一个带有代码和说明的对话框或叠加层(例如:“扫描此 QR 码或访问 xbox.com/play 并输入代码 ABCD 以登录”)。
   • Close 事件 —— 当远程登录过程完成或被取消时触发,提示游戏隐藏或关闭代码对话框。
2. 用户登录发起 —— 调用 XUserAddAsync 添加新用户时,如果尚无本地用户登录,XUser 系统可能会使用 Remote Connect 流程(尤其是在无头或第三方平台上)。
3. 代码显示 —— XUser 调用“show”回调,提供身份验证代码或 URL。游戏的 UI 处理程序(例如 OnRemoteConnectShow)向用户显示 QR 码或代码字符串。
4. 用户身份验证 —— 玩家使用手机或 Web 浏览器通过所提供的代码登录,将其 XBOX 账户关联到当前会话。
5. 完成 —— 身份验证在后端完成后,XUser 调用“close”回调,示意可以从屏幕上移除代码。此时,XUser 已获取用户的 XBOX Live 令牌,并创建 XUserHandle。
6. 成功 —— XUserAddAsync 任务成功返回,用户在没有直接在设备上输入凭据的情况下即已登录。

​

实现

XUserPlatformRemoteConnectEventHandlers remoteConnect = {};
remoteConnect.context = nullptr;
remoteConnect.show = &OnRemoteConnectShow;   // Display QR/code dialog
remoteConnect.close = &OnRemoteConnectClose; // Dismiss dialog

HRESULT hr = XUserPlatformRemoteConnectSetEventHandlers(nullptr, &remoteConnect);

​

用户体验注意事项

• 清晰的说明 —— 在显示代码时清楚地说明用户需要做什么。
• 错误处理 —— 如果用户在远端取消或发生错误,XUser 会使登录尝试失败。请在 XUserAddAsync 的正常完成回调中处理这种情况。
• 及时关闭 —— 当 close 事件发生时立即隐藏代码,以避免用户困惑。
• 视觉设计 —— 确保 QR 码和说明在目标设备上足够大且清晰可见。

​

单会话强制(SPoP)

​

工作原理

​

流程

1. 事件处理程序注册 —— 游戏在发起登录之前,使用 XUserPlatformSpopPromptSetEventHandlers(...) 注册 SPoP 提示事件处理程序。
2. 冲突检测 —— 调用 XUserAddAsync 添加用户时,如果 XUser 检测到相同用户已在其他地方在同一款游戏中处于活动状态,则会调用 SPoP 处理程序。
3. 显示提示 —— 游戏的处理程序会接收到用户的现代玩家代号和一个操作句柄。处理程序应显示一个 UI 提示,例如:“[Gamertag] 正在另一台设备上游玩。你想改在这里游玩(这会在别处注销),还是切换到其他账户?”,并提供“在此处游玩”和“切换账户”等选项。
4. 用户选择 —— 游戏等待用户做出选择。在游戏调用完成 API 之前,操作保持挂起。
5. 完成操作 —— 根据用户的选择,游戏使用相应的结果调用 XUserPlatformSpopPromptComplete:
   • 在此处游玩 —— XUserPlatformSpopOperationResult::SignInHere —— 在此设备上登录并终止远端会话。
   • 切换账户 —— XUserPlatformSpopOperationResult::SwitchAccount —— 取消在此设备上的登录,允许用户选择其他账户。
   • 取消 —— XUserPlatformSpopOperationResult::Canceled —— 中止登录尝试。
6. 处置结果 —— XUser 根据结果继续。如果选择了“在此处游玩”,远端会话会被终止(另一台设备会收到注销事件),并且用户在本地处于活动状态。如果选择了“切换账户”,XUserAddAsync 会失败,游戏可以提示选择不同的账户。

​

实现

HRESULT hr = XUserPlatformSpopPromptSetEventHandlers(nullptr, &OnSpopPrompt, nullptr);

// If user chose "Play here"
XUserPlatformSpopPromptComplete(operation, XUserPlatformSpopOperationResult::SignInHere);

// If user chose "Switch account"
XUserPlatformSpopPromptComplete(operation, XUserPlatformSpopOperationResult::SwitchAccount);

// If dialog was canceled
XUserPlatformSpopPromptComplete(operation, XUserPlatformSpopOperationResult::Canceled);

​

用户体验注意事项

• 清晰的信息 —— 显示用户的玩家代号,并清楚地说明继续操作会在另一台设备上将其注销。
• 可见的选项 —— 让“在此处游玩”和“切换账户”这两个选项清晰可见、易于理解。
• 防止存档冲突 —— 强调这样做可以防止游戏存档冲突和并发游玩问题。
• 平台特定行为 —— 在 XBOX 和 Windows 上,操作系统会自动处理这些情况,SPoP 处理程序永远不会被调用。在其他平台上,你的游戏负责呈现此选择。

​

另请参见