> ## 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 整合

> 讓玩家登入 XBOX 服務與 PlayFab、佈建連結帳戶，並透過 PlayFab 經濟系統為 GDK 遊戲串接 Microsoft Store 應用程式內購買。

PlayFab 是 Microsoft 為線上遊戲提供的後端即服務，涵蓋經濟系統、目錄、排行榜、雲端指令碼、分析、配對，以及 PlayFab Party 語音/資料網路。它能順暢地疊加在 XBOX 服務之上。XBOX 服務負責**面向玩家的身分識別** (玩家代號、好友、成就、狀態、MPSD 工作階段)，而 PlayFab 負責**後端線上服務資料** (物品欄、貨幣、自訂使用者資料、遙測)。

任何使用 **PlayFab Party**、使用 PlayFab 經濟系統進行 **Microsoft Store 應用程式內購買**、PlayFab 排行榜或任何其他 PlayFab 服務的 GDK 遊戲，都必須讓玩家登入**兩個**堆疊，並讓兩個身分識別保持連結。

> [!NOTE]
>
> 本頁著重於整合的 XBOX 端：如何佈建與已登入 XUser 綁定的 PlayFab 帳戶，以及 Microsoft Store 權利流程如何串接至 PlayFab 經濟系統。如需完整的 PlayFab 功能範圍 (Game Manager、目錄、雲端指令碼、配對、Party)，請參閱 [PlayFab 文件](https://learn.microsoft.com/gaming/services/playfab/)。

## XBOX 與 PlayFab 使用者帳戶

XBOX 服務帳戶與 PlayFab 帳戶是兩個獨立的身分識別：

* **XBOX 服務帳戶**：面向玩家。由玩家的 Microsoft 帳戶 (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 帳戶已連結，且遊戲持有有效的認證 (Entity ID + PlayFab 權杖)，可用於經過驗證的 PlayFab REST/SDK 呼叫。

> [!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 中開啟專案 → **Project** → **Properties**。
   * 在 **Configuration Properties** → **Gaming Desktop** → **General** 下，開啟 **Gaming Extension Libraries** 並新增 **PlayFab.Services.C**。

**建議的登入流程**

1. 使用 [`XUserAddAsync`](https://docs.xbox.com/zh-TW/reference/system/xuser/xuser_members) 讓玩家登入其 XBOX 帳戶，並保留傳回的 `XUserHandle`。
2. 呼叫 `PFAuthenticationLoginWithXUserAsync`：
   * 將 `XUserHandle` 作為 `user` 參數傳遞。
   * 設定 `createAccount = TRUE`，讓 PlayFab 在首次登入時自動佈建連結的帳戶。
3. 在工作階段期間保存產生的 PlayFab 認證 (Entity ID + PlayFab 權杖)，並將其用於所有後續的 PlayFab 呼叫。

如需完整的逐步解說，請參閱 [GDK 的 PlayFab Services SDK 快速入門](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. 成功時，您會收到攜帶 PlayFab Entity ID 與權杖的 `PartyXblLoginToPlayFabCompletedStateChange`。

> [!NOTE]
>
> 對於**遠端**使用者，請使用 `PartyXblManager::CreateRemoteChatUser`，遠端使用者流程不需要驗證或權杖交換。

## XUser 是身分識別的橋樑

所有下游作業 (PlayFab 登入、MPSD 工作階段寫入權杖、S2S 呼叫、權利查詢) 都從 `XUserAddAsync` 傳回的 `XUserHandle` 開始。有兩個 API 對 PlayFab 整合很重要：

| API | 用途 |
| - | - |
| [`XUserAddAsync`](https://docs.xbox.com/zh-TW/reference/system/xuser/xuser_members) | 讓玩家登入其 XBOX 帳戶並取得 `XUserHandle`。 |
| `XUserGetTokenAndSignatureUtf16Async` | 為協助程式庫路徑 (Win32 後援) 或任何自訂 S2S 橋接器擷取 XBOX 服務權杖 + 簽章。 |

如需更廣泛的登入模型 (MSA、XSTS 權杖、沙箱範圍)，請參閱 [XBOX 服務身分識別](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/identity/xs-identity-overview.md)。

## 跨平台遊戲

PlayFab 支援許多平台驗證提供者。當您在 iOS、Android、Steam 或 PlayStation 上發行同一款遊戲時，**請勿**嘗試讓每位玩家都經由 XUser，而應使用該平台原生的 PlayFab 驗證提供者：

* **iOS**：Apple ID (`LoginWithApple`)。
* **Android**：Google Play 遊戲 (`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 遊戲)。通用 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 的 **Game setup → XBOX services** 下，選擇 **Use full XBOX services feature set (requires concept approval)** 或 **Use XBOX Creators Program**，然後在您的遊戲下建立附加元件。

> [!NOTE]
>
> PlayFab 的 Microsoft Store 附加元件**不支援** Partner Center 中的**商店管理消耗品**。請只建立**開發人員管理的消耗品** (或耐久品)。

### 在 Partner Center 與 PlayFab 中建立相符的項目

Partner Center 中的 **Product ID** 與 PlayFab 中的 **Item ID** 必須完全相符，權利同步才能運作。

1. 在 Partner Center → **Add-ons** → **Create a new Consumable (Developer-managed)** (或 Durable)。輸入唯一的 **Product ID** (例如 `MyItem_001`)。
2. 在 [PlayFab Game Manager](https://developer.playfab.com/) → **Engage** → **Economy** → **New item**。在 **Item ID** 中輸入相同的字串 (`MyItem_001`)。將其標示為 Consumable 或 Durable 以與 Partner Center 相符，然後儲存。

### 術語參考

| 概念 | PlayFab | Partner Center / Microsoft Store |
| - | - | - |
| 唯一識別碼 | Item ID | Product ID |
| 消耗品 | Consumable | Consumable (Developer-managed) |
| 耐久品 | Durable | Durable *或* Durable with packages |
| 虛擬遊戲內商店 | Store | *(不適用)* |

### 目錄與商店：全域唯一的 Item ID

PlayFab 允許您為每個遊戲定義多個**目錄**，而在每個目錄中，您可以將項目分組到**商店**中。若要讓 Microsoft Store 權利同步運作，**每個 Product ID 必須與 PlayFab 遊戲中所有目錄版本內的恰好一個 Item ID 相符。**

> [!WARNING]
>
> 如果相同的 `Item ID` 出現在多個目錄中，權利取用將會失敗。請讓項目 ID 在指定 PlayFab 遊戲的每個目錄之間保持全域唯一。

**錯誤：在多個目錄中重複使用相同 ID：**

| 目錄版本 | Item ID | 類型 |
| - | - | - |
| MyCatalog\_001 | MyItem\_001 | Consumable |
| MyCatalog\_002 | MyItem\_001 | Consumable |
| MyCatalog\_003 | MyItem\_001 | Durable |

**正確：每個 SKU 一個 Item ID，可在多個商店中自由重複使用：**

| 目錄版本 | Item ID | 類型 |
| - | - | - |
| MyCatalog\_001 | MyItem\_001 | Consumable |
| MyCatalog\_001 | MyItem\_002 | Durable |
| MyCatalog\_002 | MyItem\_003 | Consumable |
| MyCatalog\_003 | MyItem\_004 | Durable |

接著，目錄內的商店就可以自由組合這些唯一項目的任何子集：

| 商店 ID | Item ID |
| - | - |
| MyStore\_001 | MyItem\_001, MyItem\_002 |
| MyStore\_002 | MyItem\_001 |
| MyStore\_003 | MyItem\_002, MyItem\_003, MyItem\_004 |

## 另請參閱

* [XBOX 服務身分識別](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/identity/xs-identity-overview.md)：XUser、MSA、XSTS 權杖、沙箱範圍。
* [XBOX 多人遊戲](https://docs.xbox.com/zh-TW/services/xbox-services/multiplayer/index.md)：PlayFab Party 作為多人遊戲傳輸選項。
* [Game Chat 2](https://docs.xbox.com/zh-TW/services/xbox-services/multiplayer/chat/game-chat2/game-chat-2-intro.md)：疊加在 PlayFab Party 之上的 Game Chat 2。
* [多人遊戲活動](https://docs.xbox.com/zh-TW/services/xbox-services/multiplayer/mpa/live-mpa-overview.md)：MPA + PlayFab Party 整合。
* [GDK 的 PlayFab Services SDK 快速入門](https://learn.microsoft.com/gaming/services/playfab/sdks/gdk/quickstart)
* [PlayFab 定價](https://playfab.com/pricing/)


## Related topics

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