Migrar del SDK independiente v1 de PlayFab al SDK unificado v2

​

Información general de los cambios

• Arquitectura unificada: todos los servicios de PlayFab (Core, Services, Party, Multiplayer, GameSave) están integrados en un solo SDK
• Autenticación simplificada: un inicio de sesión proporciona acceso a todos los servicios de PlayFab mediante identificadores de entidad
• Administración automática de tokens: se acabó la actualización manual de tokens y la administración de identificadores de entidad
• Interoperabilidad mejorada: comunicación fluida entre los diferentes servicios de PlayFab
• Estructura de proyecto simplificada: una única instalación de SDK en lugar de varios paquetes independientes

​

Cambios en la estructura del proyecto

​

Para usuarios del GDK

• Extensiones independientes para cada componente del SDK
• Carpetas de inclusión y de bibliotecas individuales: PlayFab.Services.Cpp, PlayFab.Party.Cpp, PlayFab.Multiplayer.Cpp
• Cada servicio tenía nombres de ExtensionLibrary distintos en el GDK
• Se requerían varias descargas para los diferentes servicios de PlayFab desde GitHub

• Un único SDK unificado de PlayFab
• Estructura organizada por plataforma con subcarpetas (xbox, windows, etc.)
• Todos los encabezados consolidados en una sola carpeta de inclusión (Core, Services, Multiplayer, Party, GameSave)
• Bibliotecas combinadas en una carpeta lib unificada

​

Actualización de las referencias del proyecto

1. Quite las referencias antiguas: elimine las referencias a PlayFab.Services.Cpp, PlayFab.Party.Cpp y otras extensiones de SDK individuales
2. Agregue la referencia unificada: haga referencia al nuevo SDK unificado de PlayFab o actualice las rutas de inclusión y de bibliotecas a las ubicaciones unificadas
3. Planifique para el futuro: Microsoft quitará las carpetas antiguas en futuras versiones del GDK (posiblemente para 2026), así que actualice los archivos del proyecto en consecuencia

​

Para usuarios de GitHub/independientes

• Reemplace las descargas de varios SDK por el paquete único del SDK unificado
• Actualice las rutas del proyecto para usar la nueva estructura de carpetas organizada por plataforma

​

Autenticación y manejo de entidades

​

Cambios en la administración de tokens

• Recuperación manual de tokens mediante PFAuthenticationGetEntityTokenAsync
• Actualización manual de tokens cuando expiran
• Paso de cadenas de identificador de entidad y token a otros servicios (por ejemplo, partyManager.CreateLocalUser(entityId, titlePlayerEntityToken, &localUser))

• Administración automática de tokens por parte del SDK de Core
• Actualización de tokens en segundo plano antes de que expiren
• Paso de PFEntityHandle directamente a otros servicios (por ejemplo, partyManager.CreateLocalUser(entityHandle, &localUser))

​

Pasos de migración para la autenticación

1. Quite la administración manual de tokens: elimine el código que recupera o comprueba manualmente los tokens de PlayFab
2. Almacene los identificadores de entidad: conserve el PFEntityHandle del inicio de sesión y úselo en todos los servicios de PlayFab
3. Actualice las llamadas a los servicios: reemplace los parámetros de identificador de entidad/token por identificadores de entidad
4. Controle la reautenticación: use las API PFAuthenticationReLogin*Async para escenarios de reautenticación

​

Cambios importantes en la API por componente

​

PlayFab Core

• La mayoría de las llamadas al servicio de Core permanecen sin cambios
• Actualice las rutas de inclusión para que apunten a los encabezados del SDK unificado

​

PlayFab Services

• La mayoría de las llamadas a los servicios permanecen sin cambios
• Actualice las rutas de inclusión para que apunten a los encabezados del SDK unificado

​

PlayFab Party (redes/voz)

​

Cambios en la inicialización

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

​

Cambios en la creación de usuarios locales

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

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

​

Pasos de migración para Party

1. Actualice la inicialización: reemplace la llamada simple a PartyManager::Initialize() por el enfoque con estructura de configuración
2. Quite la recuperación de tokens: elimine cualquier código que obtenga manualmente el identificador de entidad/token para Party
3. Pase identificadores de entidad: use PFEntityHandle directamente en lugar de parámetros de cadena
4. Quite la lógica de actualización de tokens: elimine el código que comprueba o actualiza periódicamente los tokens de Party
5. Actualice las dependencias: asegúrese de que PlayFab Core se inicialice antes de PartyManager::Initialize()
6. Quite las llamadas específicas de XBOX: reemplace PartyXblManagerInitialize() por el genérico PartyInitialize() en XBOX

​

PlayFab Multiplayer (Lobby y Matchmaking)

​

Cambios en las operaciones de Lobby

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

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

​

Pasos de migración para Multiplayer

1. Actualice las llamadas a funciones: reemplace los parámetros de identificador de PlayFab y token de entidad por PFEntityHandle
2. Quite los pasos de autenticación: elimine las llamadas independientes de “Authenticate Multiplayer”
3. Inicialice explícitamente: llame a PFMultiplayerInitialize() y posiblemente a PFMultiplayerStartProcessing()
4. Actualice el matchmaking: use identificadores de entidad en la creación de tickets de matchmaking

​

Lista de comprobación general de migración

​

Actualizaciones de código

• Actualice las rutas de inclusión: apunte al directorio de inclusión del SDK unificado
• Actualice la vinculación de bibliotecas: vincule las bibliotecas unificadas en lugar de las independientes
• Quite las funciones en desuso: elimine las llamadas a funciones eliminadas como PartyManager::CreateLocalUserWithEntityType
• Reemplace la administración manual de tokens: quite la lógica de almacenamiento en caché y actualización de tokens
• Actualice el orden de inicialización: asegúrese de que PlayFab Core se inicialice antes que los demás servicios

​

Lista de comprobación de pruebas

• Autenticación: el inicio de sesión devuelve un identificador de entidad válido
• Operaciones de Lobby: la creación y unión a salas funciona correctamente
• Redes de Party: los jugadores pueden conectarse y comunicarse entre máquinas
• Control de errores: todas las llamadas a PlayFab controlan los errores adecuadamente
• Escenarios multiusuario: varios usuarios locales funcionan si corresponde

​

Problemas comunes y soluciones

• Compruebe si las firmas de las funciones cambiaron para requerir PFEntityHandle
• Asegúrese de pasar el identificador de entidad en lugar de identificadores de cadena

• Verifique que PlayFab Core se inicialice antes que los demás servicios
• Compruebe que el inicio de sesión se complete antes de crear usuarios locales en Party/Multiplayer

• Poco frecuentes, pero verifique que v2 no presente problemas en rutas de código críticas para el rendimiento

​

Ventajas de la migración

​

Simplificación del código

• Complejidad reducida: quite el código de soluciones alternativas para la separación de servicios de v1
• Control de errores unificado: todos los servicios de PlayFab usan una notificación de errores coherente
• Autenticación centralizada: un solo flujo de inicio de sesión para todas las características de PlayFab

​

Interoperabilidad mejorada

• Integración fluida: agregar nuevas características de PlayFab requiere una configuración mínima
• Mejor compatibilidad multiusuario: el SDK unificado maneja varios usuarios locales de manera más eficaz
• Modelo de entidad coherente: el mismo enfoque de autenticación en todos los servicios

​

Preparación para el futuro

• Desarrollo activo: v2 es la versión mantenida activamente
• Nuevas características: las futuras capacidades de PlayFab se dirigirán al SDK unificado
• Soporte a largo plazo: los SDK v1 quedarán en desuso con el tiempo

​

Pasos siguientes

1. Actualice la estructura del proyecto: migre al diseño del SDK unificado
2. Refactorice la autenticación: implemente el enfoque basado en identificadores de entidad
3. Pruebe exhaustivamente: valide que toda la funcionalidad de PlayFab funcione correctamente
4. Limpie el código: quite las soluciones alternativas en desuso de v1 y la administración manual de tokens
5. Supervise el rendimiento: asegúrese de que la migración no introduzca problemas de rendimiento