從 PlayFab 獨立 SDK v1 移轉至 Unified SDK v2

​

變更概觀

• 統一架構：所有 PlayFab 服務 (Core、Services、Party、Multiplayer、GameSave) 都整合至單一 SDK 中
• 簡化驗證：只需登入一次，即可透過實體控制代碼存取所有 PlayFab 服務
• 自動權杖管理：不再需要手動重新整理權杖或管理實體識別碼
• 改善互通性：不同 PlayFab 服務之間的順暢通訊
• 簡化專案結構：單一 SDK 安裝，而非多個個別套件

​

專案結構變更

​

適用於 GDK 使用者

• 每個 SDK 元件都有個別的延伸模組
• 個別的 include 和程式庫資料夾：PlayFab.Services.Cpp、PlayFab.Party.Cpp、PlayFab.Multiplayer.Cpp
• 每個服務在 GDK 中都有不同的 ExtensionLibrary 名稱
• 不同的 PlayFab 服務需要從 GitHub 進行多次下載

• 單一統一的 PlayFab SDK
• 依平台組織的結構，包含子資料夾 (xbox、windows 等)
• 所有標頭都整合在一個 includes 資料夾中 (Core、Services、Multiplayer、Party、GameSave)
• 統一 lib 資料夾中的合併程式庫

​

更新您的專案參考

1. 移除舊參考：刪除對 PlayFab.Services.Cpp、PlayFab.Party.Cpp 和其他個別 SDK 延伸模組的參考
2. 新增統一參考：參考新的 PlayFab Unified SDK，或將 include/程式庫路徑更新為統一位置
3. 為未來做規劃：Microsoft 將在未來的 GDK 版本中移除舊資料夾 (可能在 2026 年之前)，因此請據此更新專案檔案

​

適用於 GitHub/獨立使用者

• 以單一 Unified SDK 套件取代多次 SDK 下載
• 更新專案路徑以使用新的依平台組織的資料夾結構

​

驗證和實體處理

​

權杖管理變更

• 使用 PFAuthenticationGetEntityTokenAsync 手動擷取權杖
• 權杖到期時手動重新整理權杖
• 將實體識別碼和權杖字串傳遞至其他服務 (例如 partyManager.CreateLocalUser(entityId, titlePlayerEntityToken, &localUser))

• 由 Core SDK 自動管理權杖
• 在到期前於背景重新整理權杖
• 直接將 PFEntityHandle 傳遞至其他服務 (例如 partyManager.CreateLocalUser(entityHandle, &localUser))

​

驗證的移轉步驟

1. 移除手動權杖管理：刪除手動擷取或檢查 PlayFab 權杖的程式碼
2. 儲存實體控制代碼：保留登入時取得的 PFEntityHandle，並在所有 PlayFab 服務中使用
3. 更新服務呼叫：以實體控制代碼取代實體識別碼/權杖參數
4. 處理重新驗證：在重新驗證案例中使用 PFAuthenticationReLogin*Async API

​

各元件的中斷性 API 變更

​

PlayFab Core

• 大多數 Core 服務呼叫維持不變
• 更新 include 路徑以指向 Unified SDK 標頭

​

PlayFab Services

• 大多數 Service 呼叫維持不變
• 更新 include 路徑以指向 Unified SDK 標頭

​

PlayFab Party (網路/語音)

​

初始化變更

PartyManager& partyManager = PartyManager::GetSingleton();
PartyError err = partyManager.Initialize("YOUR_PLAYFAB_TITLE_ID");

PartyManager& partyManager = PartyManager::GetSingleton();

PartyInitializationConfiguration partyInitConfig = {};
partyInitConfig.titleId = "YOUR_PLAYFAB_TITLE_ID";
partyInitConfig.audioTaskQueue = nullptr;
partyInitConfig.networkingTaskQueue = nullptr;

PartyError err = partyManager.Initialize(&partyInitConfig);

​

本機使用者建立變更

PartyLocalUser* localUser = nullptr;
PartyError err = partyManager.CreateLocalUser(entityId, titlePlayerEntityToken, &localUser);

PartyLocalUser* localUser = nullptr;
PartyError err = partyManager.CreateLocalUser(entityHandle, &localUser);

​

Party 的移轉步驟

1. 更新初始化：以設定結構方法取代簡單的 PartyManager::Initialize() 呼叫
2. 移除權杖擷取：刪除任何為 Party 手動取得實體識別碼/權杖的程式碼
3. 傳遞實體控制代碼：直接使用 PFEntityHandle，而非字串參數
4. 移除權杖重新整理邏輯：刪除定期檢查或重新整理 Party 權杖的程式碼
5. 更新相依性：確定在 PartyManager::Initialize() 之前已初始化 PlayFab Core
6. 移除 XBOX 特定呼叫：在 XBOX 上以一般的 PartyInitialize() 取代 PartyXblManagerInitialize()

​

PlayFab Multiplayer (Lobby 與 Matchmaking)

​

Lobby 作業變更

PFEntityKey newMember{ entityId, entityType };
HRESULT hr = PFMultiplayerJoinLobby(pfmHandle, &newMember, connectionString, &joinConfig, nullptr, &lobby);

HRESULT hr = PFMultiplayerJoinLobbyWithEntityHandle(pfmHandle, entityHandle, connectionString, &joinConfig, nullptr, &lobby);

​

Multiplayer 的移轉步驟

1. 更新函式呼叫：以 PFEntityHandle 取代 PlayFab 識別碼和實體權杖參數
2. 移除驗證步驟：刪除個別的「驗證 Multiplayer」呼叫
3. 明確初始化：呼叫 PFMultiplayerInitialize()，並視需要呼叫 PFMultiplayerStartProcessing()
4. 更新配對：在建立配對票證時使用實體控制代碼

​

一般移轉檢查清單

​

程式碼更新

• 更新 include 路徑：指向 Unified SDK include 目錄
• 更新程式庫連結：連結統一程式庫，而非個別程式庫
• 移除已淘汰的函式：刪除對已移除函式 (例如 PartyManager::CreateLocalUserWithEntityType) 的呼叫
• 取代手動權杖管理：移除權杖快取和重新整理邏輯
• 更新初始化順序：確定 PlayFab Core 在其他服務之前初始化

​

測試檢查清單

• 驗證：登入會傳回有效的實體控制代碼
• Lobby 作業：建立/加入大廳正常運作
• Party 網路：玩家可以跨電腦連線和通訊
• 錯誤處理：所有 PlayFab 呼叫都能適當地處理錯誤
• 多使用者案例：如果適用，多個本機使用者都能正常運作

​

常見問題和解決方案

• 檢查函式簽章是否已變更為需要 PFEntityHandle
• 確定您傳遞的是實體控制代碼，而非字串識別碼

• 確認 PlayFab Core 在其他服務之前初始化
• 檢查登入是否在 Party/Multiplayer 中建立本機使用者之前完成

• 很少見，但請確認 v2 不會在效能關鍵的程式碼路徑中造成問題

​

移轉的優點

​

簡化程式碼

• 降低複雜度：移除因應 v1 服務分離的因應措施程式碼
• 統一錯誤處理：所有 PlayFab 服務都使用一致的錯誤回報
• 集中式驗證：所有 PlayFab 功能使用同一個登入流程

​

改善互通性

• 順暢整合：新增 PlayFab 功能只需極少的設定
• 更好的多使用者支援：Unified SDK 能更有效地處理多個本機使用者
• 一致的實體模型：所有服務使用相同的驗證方法

​

面向未來

• 持續開發：v2 是持續維護的版本
• 新功能：未來的 PlayFab 功能將以 Unified SDK 為目標
• 長期支援：v1 SDK 最終將會淘汰

​

後續步驟

1. 更新專案結構：移轉至 Unified SDK 配置
2. 重構驗證：實作以實體控制代碼為基礎的方法
3. 徹底測試：驗證所有 PlayFab 功能都能正常運作
4. 清除程式碼：移除已淘汰的 v1 因應措施和手動權杖管理
5. 監視效能：確保移轉不會造成效能問題