Migration Guide: PlayFab Standalone SDK (v1) to PlayFab Unified SDK (v2)

​

Overview of Changes

• Unified architecture: All PlayFab services (Core, Services, Party, Multiplayer, GameSave) are integrated into a single SDK
• Simplified authentication: One login provides access to all PlayFab services through entity handles
• Automatic token management: No more manual token refresh or entity ID management
• Improved interoperability: Seamless communication between different PlayFab services
• Streamlined project structure: Single SDK installation instead of multiple separate packages

​

Project Structure Changes

​

For GDK Users

• Separate extensions for each SDK component
• Individual include and library folders: PlayFab.Services.Cpp, PlayFab.Party.Cpp, PlayFab.Multiplayer.Cpp
• Each service had distinct ExtensionLibrary names in GDK
• Multiple downloads required for different PlayFab services from GitHub

• Single unified PlayFab SDK
• Platform-organized structure with subfolders (xbox, windows, etc.)
• All headers consolidated in one includes folder (Core, Services, Multiplayer, Party, GameSave)
• Combined libraries in unified lib folder

​

Updating Your Project References

1. Remove old references: Delete references to PlayFab.Services.Cpp, PlayFab.Party.Cpp, and other individual SDK extensions
2. Add unified reference: Reference the new PlayFab Unified SDK or update include/library paths to the unified locations
3. Plan for future: Microsoft will remove old folders in future GDK releases (possibly by 2026), so update project files accordingly

​

For GitHub/Standalone Users

• Replace multiple SDK downloads with the single unified SDK package
• Update project paths to use the new platform-organized folder structure

​

Authentication and Entity Handling

​

Token Management Changes

• Manual token retrieval using PFAuthenticationGetEntityTokenAsync
• Manual token refresh when tokens expire
• Passing entity ID and token strings to other services (e.g., partyManager.CreateLocalUser(entityId, titlePlayerEntityToken, &localUser))

• Automatic token management by the Core SDK
• Background token refresh before expiry
• Pass PFEntityHandle directly to other services (e.g., partyManager.CreateLocalUser(entityHandle, &localUser))

​

Migration Steps for Authentication

1. Remove manual token management: Delete code that manually retrieves or checks PlayFab tokens
2. Store entity handles: Keep the PFEntityHandle from login and use it across all PlayFab services
3. Update service calls: Replace entity ID/token parameters with entity handles
4. Handle re-authentication: Use PFAuthenticationReLogin*Async APIs for re-authentication scenarios

​

Breaking API Changes by Component

​

PlayFab Core

• Most Core service calls remain unchanged
• Update include paths to point to unified SDK headers

​

PlayFab Services

• Most Service calls remain unchanged
• Update include paths to point to unified SDK headers

​

PlayFab Party (Networking/Voice)

​

Initialization Changes

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);

​

Local User Creation Changes

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

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

​

Migration Steps for Party

1. Update initialization: Replace simple PartyManager::Initialize() call with configuration struct approach
2. Remove token retrieval: Delete any code that manually gets entity ID/token for Party
3. Pass entity handles: Use PFEntityHandle directly instead of string parameters
4. Remove token refresh logic: Delete code that periodically checks or refreshes Party tokens
5. Update dependencies: Ensure PlayFab Core is initialized before PartyManager::Initialize()
6. Remove XBOX-specific calls: Replace PartyXblManagerInitialize() with generic PartyInitialize() on XBOX

​

PlayFab Multiplayer (Lobby & Matchmaking)

​

Lobby Operations Changes

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

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

​

Migration Steps for Multiplayer

1. Update function calls: Replace PlayFab ID and entity token parameters with PFEntityHandle
2. Remove authentication steps: Delete separate “Authenticate Multiplayer” calls
3. Initialize explicitly: Call PFMultiplayerInitialize() and potentially PFMultiplayerStartProcessing()
4. Update matchmaking: Use entity handles in matchmaking ticket creation

​

General Migration Checklist

​

Code Updates

• Update include paths: Point to unified SDK include directory
• Update library linking: Link unified libraries instead of separate ones
• Remove deprecated functions: Delete calls to removed functions like PartyManager::CreateLocalUserWithEntityType
• Replace manual token management: Remove token caching and refresh logic
• Update initialization order: Ensure PlayFab Core initializes before other services

​

Testing Checklist

• Authentication: Login returns valid entity handle
• Lobby operations: Create/join lobbies work correctly
• Party networking: Players can connect and communicate across machines
• Error handling: All PlayFab calls handle errors appropriately
• Multi-user scenarios: Multiple local users work if applicable

​

Common Issues and Solutions

• Check if function signatures changed to require PFEntityHandle
• Ensure you’re passing the entity handle instead of string IDs

• Verify PlayFab Core is initialized before other services
• Check that login completes before creating local users in Party/Multiplayer

• Rare, but verify v2 doesn’t introduce issues in performance-critical code paths

​

Benefits of Migration

​

Code Simplification

• Reduced complexity: Remove workaround code for v1’s service separation
• Unified error handling: All PlayFab services use consistent error reporting
• Centralized authentication: One login flow for all PlayFab features

​

Improved Interoperability

• Seamless integration: Adding new PlayFab features requires minimal setup
• Better multi-user support: Unified SDK handles multiple local users more effectively
• Consistent entity model: Same authentication approach across all services

​

Future-Proofing

• Active development: v2 is the actively maintained version
• New features: Future PlayFab capabilities will target the unified SDK
• Long-term support: v1 SDKs will eventually be deprecated

​

Next Steps

1. Update project structure: Migrate to unified SDK layout
2. Refactor authentication: Implement entity handle-based approach
3. Test thoroughly: Validate all PlayFab functionality works correctly
4. Clean up code: Remove deprecated v1 workarounds and manual token management
5. Monitor performance: Ensure migration doesn’t introduce performance issues