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

# 适用于 XBOX 服务游戏的 PlayFab 集成

> 为 GDK 标题登录玩家至 XBOX 服务和 PlayFab、预配已关联账户，并通过 PlayFab Economy 接入 Microsoft Store 应用内购买。

PlayFab 是 Microsoft 为实时运营游戏提供的后端即服务 —— 涵盖经济体系、目录、排行榜、云脚本、分析、匹配以及 PlayFab Party 语音/数据网络。它可以整齐地叠加在 XBOX 服务之上。XBOX 服务负责**面向玩家的身份**（玩家代号、好友、成就、状态、MPSD 会话），而 PlayFab 负责**后端实时运营数据**（库存、货币、自定义用户数据、遥测）。

任何使用 **PlayFab Party**、通过 PlayFab Economy 进行 **Microsoft Store 应用内购买**、PlayFab 排行榜或任何其他 PlayFab 服务的 GDK 标题，都必须将玩家登录到**这两个**堆栈，并保持两个身份关联。

> [!NOTE]
>
> 本页面重点介绍集成的 XBOX 侧内容 —— 即如何预配与已登录 XUser 关联的 PlayFab 账户，以及 Microsoft Store 权益流程如何接入 PlayFab Economy。有关完整的 PlayFab 功能范围（游戏管理器、目录、云脚本、匹配、Party），请参阅 [PlayFab 文档](https://learn.microsoft.com/gaming/services/playfab/)。

## XBOX 与 PlayFab 用户账户

XBOX 服务账户与 PlayFab 账户是两个独立的身份：

* **XBOX 服务账户** —— 面向玩家。归玩家的 Microsoft Account (MSA) 所有。承载玩家代号、XUID、好友、成就、状态。
* **PlayFab 账户** —— 后端使用。由你的 **PlayFab TitleId**（在 [PlayFab Game Manager](https://developer.playfab.com/) 中创建标题时分配的 4–6 位十六进制字符串）内的 **Entity ID** 标识。与你的 XBOX 游戏 ID 不同。

若要在 GDK 标题中使用任何 PlayFab 功能（Party 语音聊天、经济体系、排行榜），每个已登录的 XUser 都必须在你的 PlayFab 标题上下文中预配一个已关联的 PlayFab 账户。登录流程结束时：

* 玩家已通过 `XUserAddAsync` 添加，并持有 `XUserHandle`。
* 该玩家在你的 PlayFab TitleId 下已存在 PlayFab 账户（首次登录时自动预配）。
* XBOX 与 PlayFab 账户已关联，且标题持有用于经过身份验证的 PlayFab REST/SDK 调用的有效凭据（Entity ID 和 PlayFab 令牌）。

> [!WARNING]
>
> 你的 PlayFab **TitleId 与你的 XBOX 游戏 ID 不同**。请在 PlayFab Game Manager 中为每款游戏（或每个分片）预配一个 PlayFab 标题，并将该 TitleId 硬编码到你的构建配置中。

## 将玩家登录到 PlayFab

有两条受支持的登录路径。请根据你所使用的 PlayFab 服务选择其一：

> [card] [PlayFab Services SDK](#playfab-services-sdk-recommended)
>
> **推荐用于所有标题。** 作为 Gaming Extension Library（`PlayFab.Services.C`）随 GDK 一起发布。适用于经济体系、排行榜、云脚本、匹配以及任何**不仅仅使用 Party** 的标题。

> [card] PlayFab Party Xbox Live Helper Library
>
> 仅当 **PlayFab Party 是你所使用的唯一 PlayFab 服务**且 XBOX 服务是你的唯一身份验证提供程序时使用。随 GDK 内的 PlayFab Party SDK 一同发布。

### PlayFab Services SDK（推荐）

PlayFab Services SDK 随 GDK 一起发布，并公开 `PFAuthenticationLoginWithXUserAsync`，它接受一个 `XUserHandle`，只需一次调用即可将玩家登录到 PlayFab。将 `createAccount = TRUE` 设置为在首次运行时自动预配已关联的 PlayFab 账户。

**设置**

1. 安装 [GDK](https://aka.ms/gdkdl)。
2. 将 **PlayFab.Services.C** Gaming Extension Library 添加到你的项目：
   * 在 Visual Studio 中打开该项目 → **项目** → **属性**。
   * 在 **配置属性** → **Gaming Desktop** → **常规**下，打开 **Gaming Extension Libraries** 并添加 **PlayFab.Services.C**。

**推荐的登录流程**

1. 使用 [`XUserAddAsync`](https://docs.xbox.com/zh-CN/reference/system/xuser/xuser_members) 将玩家登录到其 XBOX 账户，并保留返回的 `XUserHandle`。
2. 调用 `PFAuthenticationLoginWithXUserAsync`：
   * 将 `XUserHandle` 作为 `user` 参数传入。
   * 设置 `createAccount = TRUE`，以便在首次登录时 PlayFab 自动预配一个已关联的账户。
3. 保存所生成的 PlayFab 凭据（Entity ID 和 PlayFab 令牌）以供该会话使用，并在后续所有 PlayFab 调用中使用它们。

有关完整演练，请参阅 [PlayFab Services SDK GDK 快速入门](https://learn.microsoft.com/gaming/services/playfab/sdks/gdk/quickstart)。

### PlayFab Party XBOX Live Helper Library

如果 PlayFab Party 是你的标题**唯一**使用的 PlayFab 服务，则可跳过 PlayFab Services SDK，并通过 Party XBOX Live Helper Library 登录，它随 GDK 内的 PlayFab Party SDK 一同发布。

**流程**

1. 使用 `XUserAddAsync` 将玩家登录到 XBOX。
2. 首次发起聊天时，使用 `XUserGetId` 获取 XUID。
3. 通过使用 XUID 调用 `PartyXblManager::CreateLocalChatUser`，创建 **`PartyXblLocalChatUser`**。
4. 使用该用户对象调用 `PartyXblManager::LoginToPlayFab`。
   * 在 GDK（主机和 PC）以及 XDK 上，帮助程序库会在内部获取所需的 XBOX 服务令牌，使用玩家的 XBOX 凭据将其登录到 PlayFab，并在首次登录时自动创建 PlayFab 账户。以这种方式创建的账户没有附加电子邮件或用户名。
   * 在非 GDK/非 XDK 标题上（例如没有 GDK 的 PC Win32），你会收到 `PartyXblTokenAndSignatureRequestedStateChange`。请自行获取 XBOX 服务令牌，并通过 `PartyXblManager::CompleteGetTokenAndSignatureRequest` 将其传回。
5. 成功后，你会收到一个 `PartyXblLoginToPlayFabCompletedStateChange`，其中包含 PlayFab 实体 ID 和令牌。

> [!NOTE]
>
> 对于**远程**用户，请使用 `PartyXblManager::CreateRemoteChatUser` —— 远程用户流程无需进行身份验证或令牌交换。

## XUser 是身份桥梁

下游的一切 —— PlayFab 登录、MPSD 会话写入令牌、S2S 调用、权益查询 —— 都始于 `XUserAddAsync` 返回的 `XUserHandle`。对 PlayFab 集成而言，有两个 API 十分重要：

| API | 用途 |
| - | - |
| [`XUserAddAsync`](https://docs.xbox.com/zh-CN/reference/system/xuser/xuser_members) | 将玩家登录到其 XBOX 账户并获取 `XUserHandle`。 |
| `XUserGetTokenAndSignatureUtf16Async` | 为帮助程序库路径（Win32 回退）或任何自定义 S2S 桥接获取 XBOX 服务令牌和签名。 |

有关更广泛的登录模型（MSA、XSTS 令牌、沙盒范围），请参阅 [XBOX 服务身份](https://docs.xbox.com/zh-CN/services/xbox-services/fundamentals/identity/xs-identity-overview.md)。

## 跨平台标题

PlayFab 支持多种平台身份验证提供程序。当你在 iOS、Android、Steam 或 PlayStation 上发布同一标题时，**不要**尝试将每个玩家都通过 XUser 路由 —— 请使用该平台原生的 PlayFab 身份验证提供程序：

* **iOS** —— Apple ID (`LoginWithApple`)。
* **Android** —— Google Play Games (`LoginWithGoogleAccount`)。
* **Steam** —— `LoginWithSteam`。
* **XBOX / GDK PC** —— `PFAuthenticationLoginWithXUserAsync`（本页）。

每个平台的登录都会预配自己的 PlayFab 账户，并将其关联到同一个 PlayFab 标题。使用同一 PlayFab 账户跨平台的玩家将在 PlayFab 中合并其关联的身份。

有关完整矩阵，请参阅 [特定于平台的 PlayFab 身份验证](https://learn.microsoft.com/gaming/services/playfab/features/authentication/platform-specific-authentication/)。

## 通过 PlayFab Economy 进行 Microsoft Store 应用内购买

对于通过 Microsoft Store 销售应用内物品的 GDK 标题，PlayFab 充当**经济体系后端**，而 Microsoft Store 处理实际交易。PlayFab 使用**权益方法**将 Microsoft Store 购买对账到玩家的 PlayFab 库存 —— 玩家必须首先登录其 XBOX 账户。

### 流程

1. 玩家已登录到 XBOX（`XUserAddAsync`）和 PlayFab（`PFAuthenticationLoginWithXUserAsync`）。
2. 玩家通过设备上的 Microsoft Store 购买物品。
3. 你的标题通知 PlayFab 该购买。
4. PlayFab 使用 XBOX 令牌调用 [`ConsumeMicrosoftStoreEntitlements`](https://learn.microsoft.com/rest/api/services/playfab/client/platform-specific-methods/consume-microsoft-store-entitlements)，同步玩家的 PlayFab 库存，并授予任何新物品。

> [!WARNING]
>
> 对于 GDK 标题，请使用 **Microsoft Store** PlayFab 加载项和 `ConsumeMicrosoftStoreEntitlements`。**不要**使用旧版 XBOX 加载项 / `ConsumeXboxEntitlements`（该路径仅适用于 XDK 标题）。通用 Windows 平台加载项已弃用。

### Partner Center 前提条件

* 已加入 [XBOX Creators Program](https://www.xbox.com/developers/creators-program) 或托管合作伙伴。
* 已在 Partner Center 配置发布者身份，其发布者 GUID 与你的 XBOX 业务合作伙伴信息（`aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee`）相同。
* 使用 XBOX 服务的概念审批。

在 Partner Center，依次选择 **游戏设置 → XBOX 服务**，选择 **使用完整的 XBOX 服务功能集（需要概念审批）** 或 **使用 XBOX Creators Program**，然后在你的标题下创建附加内容。

> [!NOTE]
>
> PlayFab 的 Microsoft Store 加载项在 Partner Center**不支持商店托管的消耗品**。请仅创建**开发者托管的消耗品**（或耐用品）。

### 在 Partner Center 和 PlayFab 中创建匹配的物品

要使权益同步生效，Partner Center 中的 **Product ID** 与 PlayFab 中的 **Item ID** 必须完全匹配。

1. 在 Partner Center 中 → **附加内容** → **创建新的消耗品（开发者托管）**（或耐用品）。输入唯一的 **Product ID**（例如 `MyItem_001`）。
2. 在 [PlayFab Game Manager](https://developer.playfab.com/) 中 → **Engage** → **Economy** → **New item**。在 **Item ID** 中输入相同的字符串（`MyItem_001`）。将其标记为消耗品或耐用品，以与 Partner Center 保持一致，然后保存。

### 术语参考

| 概念 | PlayFab | Partner Center / Microsoft Store |
| - | - | - |
| 唯一标识符 | Item ID | Product ID |
| 消耗品 | Consumable | Consumable (Developer-managed) |
| 耐用品 | Durable | Durable *或* Durable with packages |
| 虚拟游戏内商店 | Store | *（不适用）* |

### 目录与商店 —— 全局唯一的 Item ID

PlayFab 允许你为每个标题定义多个 **Catalog**，并且你可以在每个 Catalog 内将物品分组到 **Store** 中。要使 Microsoft Store 权益同步生效，**每个 Product ID 必须在你的 PlayFab 标题的所有 Catalog 版本中恰好匹配一个 Item ID**。

> [!WARNING]
>
> 如果同一 `Item ID` 出现在多个 Catalog 中，权益消耗将会失败。请确保物品 ID 在给定 PlayFab 标题的每个 Catalog 中都全局唯一。

**错误 —— 相同 ID 在多个目录中重复使用：**

| Catalog version | Item ID | 类型 |
| - | - | - |
| MyCatalog\_001 | MyItem\_001 | Consumable |
| MyCatalog\_002 | MyItem\_001 | Consumable |
| MyCatalog\_003 | MyItem\_001 | Durable |

**正确 —— 每个 SKU 一个 Item ID，可在多个 Store 中自由复用：**

| Catalog version | Item ID | 类型 |
| - | - | - |
| MyCatalog\_001 | MyItem\_001 | Consumable |
| MyCatalog\_001 | MyItem\_002 | Durable |
| MyCatalog\_002 | MyItem\_003 | Consumable |
| MyCatalog\_003 | MyItem\_004 | Durable |

然后，Catalog 内的 Store 可以自由地捆绑这些唯一物品的任意子集：

| Store ID | Item IDs |
| - | - |
| MyStore\_001 | MyItem\_001, MyItem\_002 |
| MyStore\_002 | MyItem\_001 |
| MyStore\_003 | MyItem\_002, MyItem\_003, MyItem\_004 |

## 另请参阅

* [XBOX 服务身份](https://docs.xbox.com/zh-CN/services/xbox-services/fundamentals/identity/xs-identity-overview.md) —— XUser、MSA、XSTS 令牌、沙盒范围。
* [XBOX 多人游戏](https://docs.xbox.com/zh-CN/services/xbox-services/multiplayer/index.md) —— 将 PlayFab Party 作为多人游戏传输选项。
* [Game Chat 2](https://docs.xbox.com/zh-CN/services/xbox-services/multiplayer/chat/game-chat2/game-chat-2-intro.md) —— 叠加在 PlayFab Party 之上的 Game Chat 2。
* [Multiplayer Activity](https://docs.xbox.com/zh-CN/services/xbox-services/multiplayer/mpa/live-mpa-overview.md) —— MPA 与 PlayFab Party 集成。
* [PlayFab Services SDK GDK 快速入门](https://learn.microsoft.com/gaming/services/playfab/sdks/gdk/quickstart)
* [PlayFab 定价](https://playfab.com/pricing/)


## Related topics

- [Identity](https://docs.xbox.com/xbox-services/identity.md)
- [Multiplayer](https://docs.xbox.com/xbox-services/multiplayer.md)
- [Game Chat](https://docs.xbox.com/xbox-services/game-chat.md)
- [Multiplayer Activity](https://docs.xbox.com/xbox-services/multiplayer-activity.md)