> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XR-112 在激活时确立用户和控制器

> 游戏必须在激活时确立活动用户和已配对的控制器，并在从挂起或受限模式恢复时处理用户/控制器的变化。

# XR-112：在初次激活和恢复期间确立用户和控制器 \*

版本 2.0，2025 年 11 月 1 日

游戏必须确立一个或多个活动用户，作为游戏中的主用户，并在从挂起和受限模式恢复时处理这些用户。在 GDK 中，游戏可通过使用简化用户模型（Simplified User Model）或高级用户模型（Advanced User Model）来实现这一点。

**使用 GDK 简化用户模型的游戏**

GDK 中的简化用户模型代替游戏处理默认用户的获取。游戏仍然负责确保控制器被分配给该用户，并使用该控制器进行游戏输入。如果没有控制器分配给默认用户，游戏应使用 `XUserFindControllerForUserWithUiAsync` 调用系统对话框来选择控制器，并开始接受玩家的输入。

**使用 GDK 高级用户模型、ERA 以及 UWP 多用户应用的游戏**

在初次激活时，游戏可以根据其游戏设计和偏好选择初始用户——可以使用启动游戏的用户，也可以显式提示选择用户。

游戏必须在对该用户的配置文件采取任何与其相关的操作（例如保存进度或设置）之前，指明活动用户。

所有使用高级用户模型的 XBOX 游戏开发工具包（GDK）游戏、ERA 游戏以及 UWP 多用户应用（MUA）游戏都必须提供进入账户选择器（account picker）以更改活动用户的入口。

当游戏从挂起或受限模式恢复时，游戏必须验证用户/控制器的配对情况，并相应地做出响应——恢复先前用户的会话，或获取一个或多个新用户。

## 更多信息

### 在初次激活期间确立用户

**GDK 简化用户模型**

初始用户通过调用 `XUserAddAsync(silent)` 提供给游戏，该调用始终为启动的用户返回单个结果。

**GDK 高级用户模型、ERA 以及 UWP 多用户应用**

*如果游戏使用启动游戏的用户：*

* 对于 GDK，可通过调用 `XUserAddAsync(silent)` 确定活动用户。如果系统返回不存在默认用户，游戏必须使用不带 silent 选项的 `XUserAddAsync` 提示选择用户。这将为用户显示账户选择器。
* 对于 ERA 和 UWP，可从应用激活上下文的推荐用户（`CoreApplicationContext.CurrentUser`）中获取活动用户。如果应用激活上下文未提供推荐用户，且游戏采取了与配置文件相关的操作，则游戏必须启动账户选择器，并根据用户在其中的选择设置活动用户。

*如果提示选择用户：*

* 游戏显示参与提示（engagement prompt），并且必须显示账户选择器。用户由其选择决定。
* 对于 GDK，通过 `XUserAddAsync` 调用账户选择器。
* 对于 ERA 和 UWP，通过 `ShowAccountPickerAsync` 调用账户选择器。

如果用户选择取消登录，游戏必须通知用户：如果继续，其进度将不会被保存。

一旦从启动过程中选定或识别了用户，游戏就必须在执行任何与配置文件相关的操作之前显示玩家代号（gamertag）。对于游戏如何或在何处显示活动用户没有硬性要求。最佳实践包括在应用的主屏幕或游戏的标题菜单上显示用户的玩家头像和显示名称。

### 在初次激活期间确立控制器

当以已登录的用户启动游戏时，游戏需要遵循账户选择器或平台设置的控制器与用户绑定。每当玩家在游戏内或游戏外通过账户选择器被选中时，XBOX 平台都会将控制器绑定到该玩家。

如果游戏使用启动游戏的用户，则应使用分配给该用户的关联手柄驱动游戏玩法和交互。

### 从挂起或受限模式恢复

**GDK 简化用户模型**

XBOX 平台将确保最初启动游戏的用户仍处于活动登录状态。游戏可通过 UDA 注册变更通知；如发生变化，请使用新绑定的控制器驱动游戏。

游戏中任何其他额外用户，都需在从挂起或受限状态恢复时，按照下面高级用户模型的指导进行相应处理。

**GDK 高级用户模型、ERA 以及 UWP 多用户应用**

当游戏从挂起状态恢复或退出受限模式时，游戏必须验证用户/控制器的配对情况，并相应做出响应：

* 如果用户/控制器配对未发生变化，则游戏必须继续。
* 在 ERA 或 UWP 中，如果游戏之前的活动用户仍已登录，但对应的 User 对象是新的（通常由用户在游戏挂起期间注销后再重新登录导致），则游戏必须使用新的已登录 User 对象替换已注销的 User 对象。用法应就像用户从未注销过一样继续。
* 如果所有预期的用户都与有效但不同的控制器配对，则游戏必须更新并使用新的系统控制器配对。
* 如果预期用户没有有效的控制器，则游戏必须通过账户选择器为该用户确立一个活动控制器。
* 如果预期的玩家未登录，游戏必须将该玩家从游戏中移除，或重新确立用户和活动控制器。游戏通常通过显示账户选择器来完成此操作。如果在重新确立用户过程中选择了新用户，且游戏状态是按用户保存的，则游戏必须使用该新用户的状态进行游戏。

## 其他资源

有关使用 GDK 的玩家身份的信息，请阅读 GDK 文档中的 Users 部分。

## 认证测试用例

下表显示：如果游戏使用 GDK 简化用户模型或 GDK 高级用户模型、ERA 以及 UWP 多用户应用，XR-112 中哪些测试用例适用于该游戏。

| 测试用例                | 适用于 GDK 简化用户模型 | 适用于 GDK 高级用户模型、ERA 以及 UWP MUA |
| ------------------- | -------------- | ----------------------------- |
| 112-02 初始用户和控制器     | 否              | 是                             |
| 112-03 无已登录用户       | 否              | 是                             |
| 112-04 活动用户指示       | 是              | 是                             |
| 112-05 访问账户选择器      | 否              | 是                             |
| 112-06 处理配置文件更改     | 否              | 是                             |
| 112-07 在受限模式期间的用户更改 | 否              | 是                             |
| 112-08 在挂起期间的用户更改   | 否              | 是                             |

### 112-02 初始用户和控制器

**测试步骤**

1. 使用配置文件 A 登录并启动游戏。
2. 验证活动用户能够控制游戏。
3. 在无已登录配置文件的情况下重复步骤 1，并验证游戏会提示确立一个活动用户。
4. 确立活动用户，并验证该用户能够控制游戏。

**预期结果**

游戏必须将活动用户设置为启动游戏时的控制器/用户配对，或显示参与提示以识别控制器和用户，或显示账户选择器以登录。

**通过示例**

1. 游戏将活动用户设置为启动游戏时的控制器/用户配对。
2. 游戏显示参与提示以识别控制器和用户。
3. 游戏显示账户选择器以登录。

**不通过示例**

1. 游戏不允许用户使用首次使用的控制器控制游戏。
2. 在无已登录用户启动时，游戏未提示用户确立活动用户。

### 112-03 无已登录用户

**测试步骤**

1. 验证没有用户已登录。
2. 启动游戏并进入所有支持保存用户数据的模式。
3. 验证每种模式在发生任何数据丢失之前均为用户提供了登录的机会。
4. 取消登录机会，并验证游戏提供警告，指出进度将不会被保存。

**预期结果**

如果游戏处于通常会保存用户数据或游戏状态的模式，游戏必须为用户提供登录的机会。如果用户不登录就继续游戏，游戏必须通知用户其进度将不会被保存。

**通过示例**

1. 未登录的用户在访问通常会保存用户数据或游戏状态的游戏模式时，会被提示登录。
2. 如果用户不登录继续游戏，会被告知进度将不会保存。

**不通过示例**

1. 在通常会保存用户数据或游戏状态的模式中，未通知用户如果不登录继续，进度将不会被保存。
2. 用户是在数据已经丢失之后才被告知无法保存进度。

### 112-04 活动用户指示

**测试步骤**

1. 使用之前从未运行过该游戏且无关联存档数据的配置文件登录。
2. 启动游戏。
3. 验证游戏在执行任何与配置文件相关的操作之前，在 UI 中标明了活动用户。"与配置文件相关的操作"包括更改用户的存档或首选项、向用户配置文件保存数据、颁发成就、为用户写入统计数据，或任何其他对用户数据或状态的本地或云端使用或操作。
4. 创建一个存档。
5. 重新启动游戏，并验证游戏在执行任何与配置文件相关的操作之前，在 UI 中标明了活动用户。
6. 断开与 XBOX Live 的连接。
7. 重新启动游戏，并验证游戏在执行任何与配置文件相关的操作之前，在 UI 中标明了活动用户。

**预期结果**

游戏必须在第一次与配置文件相关的操作之前指明当前用户上下文。

**通过示例**

1. 游戏在执行任何与配置文件相关的操作之前，在游戏内显示用户的玩家代号和/或玩家头像。
2. 不使用用户配置文件的游戏不指示活动用户。
3. 对于支持多用户的游戏模式，游戏显示多个活动用户。

**不通过示例**

1. 游戏在执行与配置文件相关的操作之前没有指明游戏的活动用户。

### 112-05 访问账户选择器

**测试步骤**

1. 使用配置文件登录并启动游戏。
2. 确认游戏允许活动用户在游戏中访问账户选择器并选择另一个配置文件。

**预期结果**

游戏必须允许用户在游戏中访问账户选择器以更改活动用户。

**通过示例**

1. 游戏允许用户在游戏中访问账户选择器。

**不通过示例**

1. 游戏不允许用户在游戏中访问账户选择器。

### 112-06 处理配置文件更改

**测试步骤**

1. 使用配置文件登录并启动游戏。
2. 访问账户选择器并选择另一个配置文件。
3. 验证游戏能够做出适当反应，将活动用户上下文切换到新的配置文件。
4. 对游戏中每一个可以访问账户选择器的位置，重复步骤 1–4。

**预期结果**

游戏必须允许用户无缝地切换到另一位用户的上下文。

**通过示例**

1. 在进入账户选择器之前，游戏通知用户更改活动用户可能会导致数据丢失，并提示用户确认。
2. 游戏正确更新到新活动用户的上下文。

**不通过示例**

1. 游戏未适当地更新到新活动用户的上下文。

### 112-07 在受限模式期间的用户更改

**测试步骤**

1. 使用配置文件 A 登录并启动游戏。
2. 在游戏内不同位置，按 XBOX 按钮以约束游戏。
3. 在游戏受限期间，注销配置文件 A 并登录配置文件 B。
4. 恢复游戏。
5. 验证游戏对新的活动用户做出相应反应。

**预期结果**

当游戏从受限模式恢复时，游戏必须验证所有先前参与的用户是否仍已登录到主机。

**通过示例**

1. 应用在恢复时自动将活动用户上下文切换到配置文件 B。
2. 游戏在恢复时自动将配置文件 A 从游戏中移除，或重新确立新用户并使用该新用户的状态进行游戏。

**不通过示例**

1. 游戏未更新以将配置文件 A 从上下文中移除为活动用户。
2. 在选择新的配置文件后，游戏继续使用配置文件 A 的状态进行游戏。

### 112-08 在挂起期间的用户更改

在零售主机上，游戏在以下条件下会被挂起：

* 当主机通过将电源模式设置为"即时启动"并关机而进入"连接的待机"（Connected Standby）状态时。
* 当游戏保持失去焦点超过十分钟时。例如，启动"设置"等应用程序并让其保持焦点十分钟。

在此测试用例中，应在第 2 步验证这两种方法。

**测试步骤**

1. 登录 XBOX 配置文件并启动游戏。
2. 在游戏中的多个位置将游戏挂起。
3. 在游戏挂起期间，注销配置文件 A 并登录配置文件 B。
4. 恢复游戏，并验证游戏对新的活动用户做出相应反应。
5. 使用新的活动用户进入游戏，并验证该用户能够取得进展。

**预期结果**

当游戏从挂起状态恢复时，游戏必须验证所有先前参与的用户是否仍已登录到主机。

**通过示例**

1. 游戏在恢复时自动将活动用户上下文切换到配置文件 B。
2. 游戏在恢复时自动将配置文件 A 从游戏中移除，或重新确立新用户并使用该新用户的状态进行游戏。

**不通过示例**

1. 游戏未更新以将配置文件 A 从上下文中移除为活动用户。
2. 在选择新配置文件后，游戏继续使用配置文件 A 的状态进行游戏。


## Related topics

- [XBOX 认证概览](/zh-CN/publishing/certification/overview.md)
- [XBOX 要求 (XR) 认证参考](/zh-CN/publishing/certification/xbox-requirements.md)
- [FMA XR-115:游戏过程中添加或移除用户和控制器](/zh-CN/publishing/certification/fma/xr-115.md)
- [FMA XR-112：激活与恢复时的用户与控制器](/zh-CN/publishing/certification/fma/xr-112.md)
- [XR-115 在游戏中添加和移除用户或控制器](/zh-CN/publishing/certification/xr/xr-115.md)