> ## 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.

# 适用于 XBOX 服务标题的 PlayFab 集成

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

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

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

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

## XBOX 与 PlayFab 用户账户

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

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

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

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

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

## 将玩家登录到 PlayFab

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

<CardGroup cols={2}>
  <Card title="PlayFab Services SDK" icon="star" href="#playfab-services-sdk-recommended">
    **推荐用于所有标题。** 作为 Gaming Extension Library（`PlayFab.Services.C`）随 GDK 一起发布。适用于经济体系、排行榜、云脚本、匹配以及任何**不仅仅使用 Party** 的标题。
  </Card>

  <Card title="PlayFab Party Xbox Live Helper Library" icon="headset">
    仅当 **PlayFab Party 是你所使用的唯一 PlayFab 服务**且 XBOX 服务是你的唯一身份验证提供程序时使用。随 GDK 内的 PlayFab Party SDK 一同发布。
  </Card>
</CardGroup>

### 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`](/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 Entity ID 和令牌。

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

## XUser 是身份桥梁

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

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

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

## 跨平台标题

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 经济体系进行 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 标题）。Universal Windows Platform 附加组件已弃用。
</Warning>

### 合作伙伴中心前提条件

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

在合作伙伴中心，依次选择 **游戏设置 → XBOX 服务**，选择 **使用完整的 XBOX 服务功能集（需要概念审批）** 或 **使用 XBOX Creators Program**，然后在你的标题下创建附加组件。

<Note>
  PlayFab 的 Microsoft Store 附加组件在合作伙伴中心**不支持商店托管的消耗品**。请仅创建**开发者托管的消耗品**（或耐用品）。
</Note>

### 在合作伙伴中心和 PlayFab 中创建匹配的物品

要使权益同步生效，合作伙伴中心中的 **Product ID** 与 PlayFab 中的 **Item ID** 必须完全匹配。

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

### 术语参考

| 概念      | PlayFab    | 合作伙伴中心 / 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 中都全局唯一。
</Warning>

**错误 —— 相同 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 服务身份](/services/xbox-services/fundamentals/identity/xs-identity-overview) —— XUser、MSA、XSTS 令牌、沙盒范围。
* [XBOX 多人游戏](/services/xbox-services/multiplayer/index) —— 将 PlayFab Party 作为多人游戏传输选项。
* [Game Chat 2](/services/xbox-services/multiplayer/chat/game-chat2/game-chat-2-intro) —— 叠加在 PlayFab Party 之上的 Game Chat 2。
* [多人活动](/services/xbox-services/multiplayer/mpa/live-mpa-overview) —— 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](/xbox-services/identity.md)
- [Multiplayer](/xbox-services/multiplayer.md)
- [Game Chat](/xbox-services/game-chat.md)
- [Multiplayer Activity](/xbox-services/multiplayer-activity.md)