XBOX 服務遊戲的 PlayFab 整合

PlayFab 是 Microsoft 為線上遊戲提供的後端即服務，涵蓋經濟系統、目錄、排行榜、雲端指令碼、分析、配對，以及 PlayFab Party 語音/資料網路。它能順暢地疊加在 XBOX 服務之上。XBOX 服務負責面向玩家的身分識別 (玩家代號、好友、成就、狀態、MPSD 工作階段)，而 PlayFab 負責後端線上服務資料 (物品欄、貨幣、自訂使用者資料、遙測)。 任何使用 PlayFab Party、使用 PlayFab 經濟系統進行 Microsoft Store 應用程式內購買、PlayFab 排行榜或任何其他 PlayFab 服務的 GDK 遊戲，都必須讓玩家登入兩個堆疊，並讓兩個身分識別保持連結。

​

XBOX 與 PlayFab 使用者帳戶

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

• XBOX 服務帳戶：面向玩家。由玩家的 Microsoft 帳戶 (MSA) 擁有，包含玩家代號、XUID、好友、成就與狀態。
• PlayFab 帳戶：在幕後運作。在您的 PlayFab TitleId (您在 PlayFab Game Manager 中建立遊戲時指派的 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 呼叫。

​

讓玩家登入 PlayFab

有兩種支援的登入路徑。請根據您使用的 PlayFab 服務選擇其中一種：

​

PlayFab Services SDK (建議)

PlayFab Services SDK 隨附於 GDK 中，並公開 PFAuthenticationLoginWithXUserAsync，它接受 XUserHandle，只需一次呼叫即可讓玩家登入 PlayFab。設定 createAccount = TRUE 即可在首次執行時自動佈建連結的 PlayFab 帳戶。 設定

1. 安裝 GDK。
2. 將 PlayFab.Services.C Gaming Extension Library 新增至您的專案：
   • 在 Visual Studio 中開啟專案 → Project → Properties。
   • 在 Configuration Properties → Gaming Desktop → General 下，開啟 Gaming Extension Libraries 並新增 PlayFab.Services.C。

建議的登入流程

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

如需完整的逐步解說，請參閱 GDK 的 PlayFab Services SDK 快速入門。

​

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。

​

XUser 是身分識別的橋樑

所有下游作業 (PlayFab 登入、MPSD 工作階段寫入權杖、S2S 呼叫、權利查詢) 都從 XUserAddAsync 傳回的 XUserHandle 開始。有兩個 API 對 PlayFab 整合很重要： 如需更廣泛的登入模型 (MSA、XSTS 權杖、沙箱範圍)，請參閱 XBOX 服務身分識別。

​

跨平台遊戲

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 驗證。

​

透過 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，並同步玩家的 PlayFab 物品欄，授與任何新項目。

​

Partner Center 先決條件

• 已註冊 XBOX 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，然後在您的遊戲下建立附加元件。

​

在 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 → Engage → Economy → New item。在 Item ID 中輸入相同的字串 (MyItem_001)。將其標示為 Consumable 或 Durable 以與 Partner Center 相符，然後儲存。

​

術語參考

​

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

PlayFab 允許您為每個遊戲定義多個目錄，而在每個目錄中，您可以將項目分組到商店中。若要讓 Microsoft Store 權利同步運作，每個 Product ID 必須與 PlayFab 遊戲中所有目錄版本內的恰好一個 Item ID 相符。 錯誤：在多個目錄中重複使用相同 ID： 正確：每個 SKU 一個 Item ID，可在多個商店中自由重複使用： 接著，目錄內的商店就可以自由組合這些唯一項目的任何子集：

​

另請參閱

• XBOX 服務身分識別：XUser、MSA、XSTS 權杖、沙箱範圍。
• XBOX 多人遊戲：PlayFab Party 作為多人遊戲傳輸選項。
• Game Chat 2：疊加在 PlayFab Party 之上的 Game Chat 2。
• 多人遊戲活動：MPA + PlayFab Party 整合。
• GDK 的 PlayFab Services SDK 快速入門
• PlayFab 定價