> ## 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 迁移到统一 SDK v2

> 将 PlayFab 游戏从 v1 独立 SDK 迁移到 v2 统一 SDK，涵盖项目布局、身份验证和令牌管理变更。

本指南帮助您从旧版 PlayFab v1 SDK 迁移到新的 PlayFab 统一 SDK v2。统一 SDK 将先前独立的多个 SDK（Core、Services、Party、Multiplayer）整合为一个集成解决方案，提高互操作性并简化身份验证。

## 变更概述

PlayFab 统一 SDK v2 引入了几项关键改进：

* **统一架构**：所有 PlayFab 服务（Core、Services、Party、Multiplayer、GameSave）被集成到单个 SDK 中
* **简化的身份验证**：一次登录即可通过实体句柄访问所有 PlayFab 服务
* **自动令牌管理**：不再需要手动令牌刷新或实体 ID 管理
* **改进的互操作性**：不同 PlayFab 服务之间无缝通信
* **精简的项目结构**：单一 SDK 安装取代多个独立包

## 项目结构变更

### 适用于 GDK 用户

**旧布局（GDK 2504 及更早版本）：**

* 每个 SDK 组件都有独立的扩展
* 独立的 include 和 library 文件夹：PlayFab.Services.Cpp、PlayFab.Party.Cpp、PlayFab.Multiplayer.Cpp
* GDK 中每个服务都有独特的 ExtensionLibrary 名称
* 需要从 GitHub 下载多个不同的 PlayFab 服务包

**新布局（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 统一 SDK，或将 include/library 路径更新为统一位置
3. **规划未来**：Microsoft 将在未来的 GDK 版本中移除旧文件夹（可能在 2026 年之前），因此请相应更新项目文件

### 适用于 GitHub/独立用户

* 用单个统一 SDK 包替代多个 SDK 下载
* 更新项目路径以使用新的按平台组织的文件夹结构

## 身份验证和实体处理

两个版本都存在实体和实体令牌的概念，但在 v2 中使用方式已被简化。

### 令牌管理变更

**PlayFab 独立 SDK (v1) 方式：**

* 使用 `PFAuthenticationGetEntityTokenAsync` 手动检索令牌
* 令牌到期时手动刷新令牌
* 将实体 ID 和令牌字符串传递给其他服务（例如 `partyManager.CreateLocalUser(entityId, titlePlayerEntityToken, &localUser)`）

**PlayFab 统一 SDK (v2) 方式：**

* Core SDK 自动管理令牌
* 令牌到期前在后台刷新
* 直接将 `PFEntityHandle` 传递给其他服务（例如 `partyManager.CreateLocalUser(entityHandle, &localUser)`）

### 身份验证的迁移步骤

1. **移除手动令牌管理**：删除手动检索或检查 PlayFab 令牌的代码
2. **存储实体句柄**：保留登录返回的 `PFEntityHandle` 并在所有 PlayFab 服务中使用
3. **更新服务调用**：将实体 ID/令牌参数替换为实体句柄
4. **处理重新身份验证**：在重新身份验证场景中使用 `PFAuthenticationReLogin*Async` API

## 按组件划分的重大 API 变更

### PlayFab Core

**迁移影响**：所需更改极少

* 大多数 Core 服务调用保持不变
* 更新 include 路径以指向统一 SDK 头文件

### PlayFab Services

**迁移影响**：所需更改极少

* 大多数 Service 调用保持不变
* 更新 include 路径以指向统一 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 手动获取实体 ID/令牌的代码
3. **传递实体句柄**：使用 `PFEntityHandle` 直接替代字符串参数
4. **移除令牌刷新逻辑**：删除定期检查或刷新 Party 令牌的代码
5. **更新依赖**：确保在 `PartyManager::Initialize()` 之前已初始化 PlayFab Core
6. **移除 XBOX 特定调用**：在 XBOX 上，将 `PartyXblManagerInitialize()` 替换为通用的 `PartyInitialize()`

### 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 ID 和实体令牌参数
2. **移除身份验证步骤**：删除单独的 “Authenticate Multiplayer” 调用
3. **显式初始化**：调用 `PFMultiplayerInitialize()`，并可能调用 `PFMultiplayerStartProcessing()`
4. **更新匹配**：在匹配票据创建中使用实体句柄

## 通用迁移清单

### 代码更新

* [ ] **更新 include 路径**：指向统一 SDK 的 include 目录
* [ ] **更新库链接**：链接统一库而不是独立库
* [ ] **移除已弃用的函数**：删除对已移除函数的调用，例如 `PartyManager::CreateLocalUserWithEntityType`
* [ ] **替换手动令牌管理**：移除令牌缓存和刷新逻辑
* [ ] **更新初始化顺序**：确保 PlayFab Core 在其他服务之前初始化

### 测试清单

迁移后，请验证每个子系统：

* [ ] **身份验证**：登录返回有效的实体句柄
* [ ] **Lobby 操作**：创建/加入 lobby 正常工作
* [ ] **Party 网络**：玩家可以跨机器连接和通信
* [ ] **错误处理**：所有 PlayFab 调用能恰当处理错误
* [ ] **多用户场景**：多个本地用户可正常工作（如适用）

### 常见问题与解决方案

**关于缺少参数的编译器错误**：

* 检查函数签名是否已更改为需要 `PFEntityHandle`
* 确保您传递的是实体句柄而不是字符串 ID

**运行时身份验证失败**：

* 验证 PlayFab Core 是否在其他服务之前初始化
* 检查登录是否在 Party/Multiplayer 中创建本地用户之前完成

**性能退化**：

* 少见，但请验证 v2 未在性能关键代码路径中引入问题

## 迁移的好处

### 代码简化

* **降低复杂性**：移除针对 v1 服务分离的变通代码
* **统一错误处理**：所有 PlayFab 服务使用一致的错误报告
* **集中式身份验证**：所有 PlayFab 功能只需一个登录流程

### 改进的互操作性

* **无缝集成**：添加新的 PlayFab 功能所需设置极少
* **更好的多用户支持**：统一 SDK 更有效地处理多个本地用户
* **一致的实体模型**：所有服务采用相同的身份验证方式

### 面向未来

* **积极开发**：v2 是当前积极维护的版本
* **新功能**：未来的 PlayFab 功能将面向统一 SDK
* **长期支持**：v1 SDK 最终将被弃用

## 后续步骤

1. **更新项目结构**：迁移到统一 SDK 布局
2. **重构身份验证**：实现基于实体句柄的方式
3. **全面测试**：验证所有 PlayFab 功能能正常工作
4. **清理代码**：移除已弃用的 v1 变通代码和手动令牌管理
5. **监控性能**：确保迁移不会引入性能问题

如需其他帮助，请参阅 PlayFab 统一 SDK 文档以及针对您特定平台的示例。


## Related topics

- [PlayFab SDK 产品](/zh-CN/services/playfab/sdks/sdk-products.md)
- [PlayFab 统一 SDK](/zh-CN/services/playfab/sdks/unified-sdk/overview.md)
- [PlayFab for Unity (v2 统一版)](/zh-CN/services/playfab/sdks/unified-unity/overview.md)
- [面向 XBOX GDK 的移植指南](/zh-CN/home/build-first-title/porting-guides.md)
- [申请受保护的 SDK 和示例的访问权限](/zh-CN/services/playfab/sdks/request-access-for-sdks-samples.md)