从 PlayFab 独立 SDK v1 迁移到统一 SDK v2

​

变更概述

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

​

项目结构变更

​

适用于 GDK 用户

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

• 单一统一的 PlayFab SDK
• 按平台组织的结构，带有子文件夹（xbox、windows 等）
• 所有头文件整合在一个 includes 文件夹中（Core、Services、Multiplayer、Party、GameSave）
• 统一 lib 文件夹中的合并库

​

更新项目引用

1. 移除旧引用：删除对 PlayFab.Services.Cpp、PlayFab.Party.Cpp 和其他单独 SDK 扩展的引用
2. 添加统一引用：引用新的 PlayFab 统一 SDK，或将 include/library 路径更新为统一位置
3. 规划未来：Microsoft 将在未来的 GDK 版本中移除旧文件夹（可能在 2026 年之前），因此请相应更新项目文件

​

适用于 GitHub/独立用户

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

​

身份验证和实体处理

​

令牌管理变更

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

• 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（网络/语音）

​

初始化变更

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

​

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 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. 监控性能：确保迁移不会引入性能问题