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

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

> 將 PlayFab 遊戲從 v1 獨立 SDK 移轉至 v2 Unified SDK，涵蓋專案配置、驗證和權杖管理的變更。

本指南可協助您從較舊的 PlayFab v1 SDK 移轉至新的 PlayFab Unified SDK v2。Unified SDK 將先前分開的 SDK (Core、Services、Party、Multiplayer) 整合成單一的整合式解決方案，並改善了互通性和簡化了驗證。

## 變更概觀

PlayFab Unified SDK v2 引進了數項重要改進：

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

## 專案結構變更

### 適用於 GDK 使用者

**舊版配置 (GDK 2504 及更早版本)：**

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

**新配置 (GDK 2510 及更新版本)：**

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

#### 更新您的專案參考

在過渡期間 (GDK 2510)，舊版和新版 SDK 會並存。若要移轉：

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

### 適用於 GitHub/獨立使用者

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

## 驗證和實體處理

這兩個版本中都有實體和實體權杖的概念，但在 v2 中使用它們的方式已經簡化。

### 權杖管理變更

**PlayFab 獨立 SDK (v1) 方法：**

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

**PlayFab Unified SDK (v2) 方法：**

* 由 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 (網路/語音)

**移轉影響**：需要少量變更

#### 初始化變更

**v1 初始化：**

```cpp theme={null}
PartyManager& partyManager = PartyManager::GetSingleton();
PartyError err = partyManager.Initialize("YOUR_PLAYFAB_TITLE_ID");
```

**v2 初始化：**

```cpp theme={null}
PartyManager& partyManager = PartyManager::GetSingleton();

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

PartyError err = partyManager.Initialize(&partyInitConfig);
```

#### 本機使用者建立變更

**v1 方法：**

```cpp theme={null}
PartyLocalUser* localUser = nullptr;
PartyError err = partyManager.CreateLocalUser(entityId, titlePlayerEntityToken, &localUser);
```

**v2 方法：**

```cpp theme={null}
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、配對 Ticket) 維持不變，但函式現在預期接收實體控制代碼，而非字串。

#### Lobby 作業變更

**v1 方法：**

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

**v2 方法：**

```cpp theme={null}
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. **監視效能**：確保移轉不會造成效能問題

如需其他協助，請參閱適用於您特定平台的 PlayFab Unified SDK 文件和範例。


## Related topics

- [PlayFab SDK 產品](/zh-TW/services/playfab/sdks/sdk-products.md)
- [PlayFab Unified SDK](/zh-TW/services/playfab/sdks/unified-sdk/overview.md)
- [從 Google 登入移轉至 Play Games 登入的後援方法](/zh-TW/services/playfab/identity/player-identity/platform-specific-authentication/google-play-games-sign-in-migration-fallback.md)
- [使用 2025 年 10 月 GDK 實作 Game Saves](/zh-TW/services/playfab/player-progression/game-saves/october-2025-gdk-changes.md)
- [要求受保護 SDK 和範例的存取權](/zh-TW/services/playfab/sdks/request-access-for-sdks-samples.md)