Guía de implementación en Steam Deck para PlayFab Game Saves

​

Información general

​

Diferencias de comportamiento del motor de sincronización

• Sincronice los datos de guardado con frecuencia (por ejemplo, después de cada nivel, punto de control o progreso significativo)
• Sincronice siempre antes de mostrar confirmaciones de “salir del juego”
• Considere la sincronización en segundo plano durante las transiciones del juego
• Implemente indicadores de progreso de sincronización para garantizar la finalización antes del apagado
• Especialmente importante para dispositivos portátiles, donde el agotamiento de la batería o los apagados repentinos son habituales

​

Requisitos previos

1. Configuración del GDK de octubre de 2025 completada: Siga la guía de implementación del GDK de octubre de 2025
2. Integración de la API de Steam: Inicialización básica de la API de Steam y detección de Steam Deck
3. Elegir el enfoque de integración: Decida entre la integración con el ecosistema XBOX o con una identidad personalizada (consulte a continuación)
4. Todos los archivos DLL necesarios: Los archivos DLL del SDK unificado deben implementarse con su compilación de Steam

​

Enfoques de implementación

​

Enfoque 1: Integración con el ecosistema XBOX (recomendado)

• Sincronización multiplataforma completa: Los datos de guardado se sincronizan entre Steam Deck, las consolas XBOX, la PC de Microsoft Store y otras plataformas habilitadas para XBOX
• Integración con XBOX Live: Los jugadores usan su gamertag de XBOX y pueden acceder a las características sociales de XBOX
• Identidad de jugador unificada: El mismo perfil de jugador en todas las plataformas
• Autenticación probada: Aprovecha la madura infraestructura de autenticación de XBOX Live
• Compatibilidad con XBOX Game Studios: Integración sin problemas para los estudios propios y asociados de XBOX

• Autenticación compleja: Se requieren controladores de eventos de XUser personalizados y devoluciones de llamada de la interfaz de usuario
• Configuración de sandbox de desarrollo: Necesaria para entornos de prueba no comerciales
• Privilegios de administrador: Necesarios para las modificaciones del registro durante la configuración del sandbox
• Implementación adicional de interfaz de usuario: Cuadros de diálogo de autenticación mediante código QR y de selección de gamertag

​

Enfoque 2: Implementación con identidad personalizada (alternativa)

• Complejidad de inicio de sesión potencialmente reducida: No se requiere autenticación de usuario de XBOX
• Sin configuración del registro: No se necesita configuración de sandbox
• Sin API de XUser: Elimina los controladores de eventos complejos
• Flexibilidad de identidad personalizada: Implemente su propio sistema de identidad de jugador multiplataforma

• Administración manual de jugadores: Debe implementar su propio sistema de identidad de jugador multiplataforma
• Integración limitada con el ecosistema: Sin acceso a las características sociales de XBOX Live ni a la base de jugadores existente de XBOX
• Puente entre plataformas: Requiere soluciones personalizadas para conectar a los jugadores entre distintas plataformas
• Infraestructura de identidad adicional: Es necesario crear sistemas de identidad o integrar sistemas de terceros

​

Configuración común (ambos enfoques)

​

1. Requisitos de implementación de archivos DLL

• libHttpClient.dll - Operaciones HTTP
• PlayFabCore.dll - Autenticación y servicios principales
• PlayFabGameSave.dll - Funcionalidad de Game Saves
• xgameruntime.dll - Funcionalidades principales del SDK e inicio de sesión de XBOX

• PlayFabServices.dll - Servicios adicionales de PlayFab (recomendado)

YourGame/
├── YourGame.exe
├── libHttpClient.dll     // Required for HTTP operations
├── PlayFabCore.dll       // Required for authentication
├── PlayFabServices.dll   // Optional: For additional PlayFab services
├── PlayFabGameSave.dll   // Required for Game Saves
├── xgameruntime.dll      // Required for Xbox Live services
├── Steam_api64.dll
└── Other game files...

​

2. Requisitos previos de integración con Steam

​

Integración de la API de Steam

// Initialize Steam API
bool steamAvailable = SteamAPI_Init();

​

Detección de plataforma

bool DetectSteamDeck() {
    if (!SteamAPI_Init()) {
        return false;
    }
    
    return SteamUtils()->IsSteamRunningOnSteamDeck();
}

​

3. Implementación de las devoluciones de llamada de la interfaz de usuario

​

Devoluciones de llamada de la interfaz de usuario de Game Saves (obligatorias para ambos enfoques)

// Required Game Saves UI callbacks for Steam Deck (both approaches)
PFGameSaveUICallbacks callbacks{};
callbacks.progressCallback = OnPFGameSaveFilesUiProgress;                    // Sync progress
callbacks.syncFailedCallback = OnPFGameSaveFilesUiSyncFailed;               // Sync errors
callbacks.activeDeviceContentionCallback = OnPFGameSaveFilesUiActiveDeviceContention;  // Device conflicts
callbacks.conflictCallback = OnPFGameSaveFilesUiConflict;                   // Save conflicts
callbacks.outOfStorageCallback = OnPFGameSaveFilesUiOutOfStorage;           // Storage quota

HRESULT hr = PFGameSaveFilesSetUiCallbacks(&callbacks);
if (FAILED(hr)) {
    // Handle callback setup failure
}

// Optional: Additional active device changed callback
hr = PFGameSaveFilesSetActiveDeviceChangedCallback(&OnActiveDeviceChanged, nullptr);

• Cuadros de diálogo de progreso: Muestran el progreso de la sincronización durante las operaciones de guardado
• Control de errores: Muestran mensajes de error de sincronización y opciones de reintento
• Resolución de conflictos: Controlan los conflictos de guardado entre dispositivos
• Contención de dispositivos: Controlan los escenarios de acceso desde varios dispositivos
• Administración del almacenamiento: Notifican a los usuarios los problemas de cuota de almacenamiento

​

Enfoque 1: Integración con el ecosistema XBOX - Implementación completa

​

Información general

• Configuración común completada (secciones 1 a 3 anteriores)
• Acceso a un sandbox de desarrollo para pruebas
• Privilegios de administrador para la configuración del registro (solo desarrollo/pruebas)

​

1. Configuración del registro

// Set sandbox before Xbox Live services initialization
// Only required when testing with non-retail sandboxes
if (isSteamDeck) {
    HRESULT hr = SteamIntegration::SetSandboxForSteamDeck("XDKS.1");
    if (FAILED(hr)) {
        // Handle sandbox setup failure - requires admin privileges
        return hr;
    }
}

• Clave: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\XboxLive\Sandbox
• Valor: Id. del sandbox de desarrollo (por ejemplo, “XDKS.1”)
• Momento: Debe establecerse antes de que se inicialicen los servicios de XBOX Live
• Privilegios: Requiere acceso de administrador
• Uso: Solo es necesario para las pruebas en sandbox no comerciales (entornos de desarrollo o pruebas)

​

2. Controladores de eventos de plataforma de XUser

​

A. Controladores de eventos de conexión remota

// Handle remote authentication flow (QR code/URL)
XUserPlatformRemoteConnectEventHandlers remoteConnect{};
remoteConnect.context = nullptr;
remoteConnect.show = &OnRemoteConnectShow;     // Display QR code/URL dialog
remoteConnect.close = &OnRemoteConnectClose;   // Close authentication dialog
HRESULT hr = XUserPlatformRemoteConnectSetEventHandlers(nullptr, &remoteConnect);
if (FAILED(hr)) {
    // Handle event handler setup failure
}

​

B. Controladores de eventos de SPOP (aviso de inicio de sesión)

// Handle SPOP sign-in prompt. See sample: ShowSpopPromptDialogForXUserOnSteamDeck
HRESULT hr = XUserPlatformSpopPromptSetEventHandlers(nullptr, &OnSpopPrompt, nullptr);
if (FAILED(hr)) {
    // Handle SPOP setup failure
}

​

3. Implementación de la interfaz de usuario de autenticación

• Cuadro de diálogo de conexión remota: Muestre el código QR y la URL para que los usuarios se autentiquen en otro dispositivo
• Cuadro de diálogo de aviso de SPOP: Permita a los usuarios seleccionar o confirmar su gamertag de XBOX

​

4. Secuencia de inicialización

// 1. Check Steam availability and platform
bool steamAvailable = SteamIntegration::CheckSteamAvailability();
bool isSteamDeck = SteamIntegration::CheckIfSteamDeck();

// 2. Set Xbox Live sandbox (Steam Deck only, required for non-retail sandbox testing)
if (isSteamDeck) {
    HRESULT hr = SteamIntegration::SetSandboxForSteamDeck("XDKS.1");
    if (FAILED(hr)) {
        // Handle sandbox setup failure
        return hr;
    }
}

// 3. Initialize Xbox runtime
hr = XGameRuntimeInitialize();
if (FAILED(hr)) {
    return hr;
}

// 4. Initialize PlayFab Core and Services
hr = PFInitialize(nullptr);
if (FAILED(hr)) {
    return hr;
}
hr = PFServicesInitialize(nullptr); // Optional

// 5. Initialize XUser for Steam Deck
if (isSteamDeck) {
    hr = SteamIntegration::InitializeXUserForSteamDeck();
    if (FAILED(hr)) {
        return hr;
    }
}

// 6. Initialize Game Saves with appropriate callbacks
bool setUiCallbacks = isSteamDeck;
hr = InitializeGameSaves(setUiCallbacks);
if (FAILED(hr)) {
    return hr;
}

​

5. Implementación del cierre de sesión

void SignOutFromSteamDeck() {
    // Enumerate and delete Windows credentials with target names starting with "Xbl"
    DWORD count = 0;
    PCREDENTIALW* credentials = nullptr;
    
    if (CredEnumerateW(L"Xbl*", 0, &count, &credentials)) {
        for (DWORD i = 0; i < count; i++) {
            CredDeleteW(credentials[i]->TargetName, credentials[i]->Type, 0);
        }
        CredFree(credentials);
    }
    
    // Close Xbox user handles
    if (xboxUser) {
        XUserCloseHandle(xboxUser);
        xboxUser = nullptr;
    }
    
    // Close PlayFab user handles
    if (pfUser) {
        PFLocalUserCloseHandle(pfUser);
        pfUser = nullptr;
    }
    
    // Reset authentication state for clean re-authentication
    authenticationState = AuthState::NotAuthenticated;
}

​

6. Lista de comprobación de pruebas

• Flujo de autenticación: Pruebe la autenticación por conexión remota (código QR/URL)
• Devoluciones de llamada de la interfaz de usuario: Compruebe que todos los cuadros de diálogo de la interfaz de usuario de Game Saves se muestran correctamente
• Avisos de SPOP: Pruebe la selección y confirmación del gamertag
• Persistencia de credenciales: Pruebe la persistencia del inicio de sesión entre reinicios de la aplicación
• Cierre de sesión: Compruebe la limpieza correcta de las credenciales al cerrar sesión
• Comportamiento de sincronización: Pruebe los patrones de sincronización frecuente y la sincronización previa al apagado
• Prevención de pérdida de datos: Compruebe que se pierde un progreso mínimo en escenarios de cierre forzado
• Sincronización multiplataforma: Pruebe la sincronización de guardados entre Steam Deck, las consolas XBOX y la PC de Microsoft Store
• Configuración del registro: Compruebe que la configuración del sandbox funciona en entornos de desarrollo
• Controladores de eventos de XUser: Confirme que los controladores de conexión remota y de SPOP funcionan correctamente

​

Enfoque 2: Implementación con identidad personalizada - Implementación completa

​

Información general

• Configuración común completada (secciones 1 a 3 anteriores)
• Sistema de identidad de jugador personalizado para uso en producción

• No se requiere autenticación de XBOX
• No se necesita configuración del registro
• No se requieren privilegios de administrador
• Interfaz de usuario más sencilla (sin código QR ni selección de gamertag)

• Debe implementar su propia identidad de jugador multiplataforma
• Sin características sociales de XBOX Live
• Requiere soluciones personalizadas de puente entre plataformas

​

1. Autenticación con identidad personalizada

// Custom identity authentication
if (isSteamDeck) {
    // Development/Testing: Use Steam user identity temporarily
    // Production: Implement your own cross-platform player identity system
    // Required for production since Steam Cloud handles Steam-only sync
    
    // Option 1: OpenID Connect Integration (Recommended)
    // If your identity system supports OpenID Connect, use LoginWithOpenIdConnect:
    // PFAuthenticationLoginWithOpenIdConnectRequest request = {};
    // request.connectionId = "YourOpenIdConnectConnectionId";
    // request.idToken = "YourOpenIdConnectToken";
    // PFAuthenticationLoginWithOpenIdConnectAsync(serviceConfigHandle, &request, ...);
    
    // Option 2: Custom Integration
    // Initialize your custom authentication system
    // Connect to your user accounts/login system
    // Integrate with PlayFab Game Saves using your player identity
    
    // Initialize Game Saves with your custom identity system
    // (Implementation details depend on your specific identity integration)
}

​

2. Secuencia de inicialización

// 1. Check Steam availability and platform
bool steamAvailable = SteamIntegration::CheckSteamAvailability();
bool isSteamDeck = SteamIntegration::CheckIfSteamDeck();

// 2. Initialize Xbox runtime (still required for Game Saves infrastructure)
HRESULT hr = XGameRuntimeInitialize();
if (FAILED(hr)) {
    return hr;
}

// 3. Initialize PlayFab Core and Services
hr = PFInitialize(nullptr);
if (FAILED(hr)) {
    return hr;
}
hr = PFServicesInitialize(nullptr); // Optional

// 4. Initialize your custom player identity system
hr = InitializeCustomPlayerIdentity();
if (FAILED(hr)) {
    return hr;
}

// 5. Initialize Game Saves with custom identity system
// Option A: OpenID Connect (if your identity system supports it)
// hr = PFAuthenticationLoginWithOpenIdConnectAsync(serviceConfigHandle, &openIdRequest, ...);
// Option B: Custom authentication integration
hr = InitializeGameSavesWithCustomIdentity();
if (FAILED(hr)) {
    return hr;
}

​

3. Implementación del cierre de sesión

void SignOutFromSteamDeck() {
    // Sign-out for custom identity implementation
    // No Xbox credential cleanup needed
    
    // Clean up your custom identity system
    SignOutFromCustomIdentitySystem();
    
    // Close PlayFab user handles
    if (pfUser) {
        PFLocalUserCloseHandle(pfUser);
        pfUser = nullptr;
    }
    
    // Clear local game state as needed
    ClearLocalGameState();
}

​

4. Lista de comprobación de pruebas

• Sistema de identidad personalizado: Pruebe su sistema personalizado de autenticación e identidad de jugadores
• Autenticación de PlayFab: Pruebe el inicio de sesión de PlayFab mediante LoginWithOpenIdConnect (si usa OpenID Connect) o el método de autenticación personalizado
• Sincronización multiplataforma de Game Saves: Pruebe la sincronización de guardados en todas las plataformas de destino
• Devoluciones de llamada de la interfaz de usuario: Compruebe que todos los cuadros de diálogo de la interfaz de usuario de Game Saves se muestran correctamente
• Resolución de conflictos: Pruebe los conflictos de guardado entre dispositivos de distintas plataformas
• Comportamiento de sincronización: Pruebe los patrones de sincronización frecuente y la sincronización previa al apagado
• Prevención de pérdida de datos: Compruebe que se pierde un progreso mínimo en escenarios de cierre forzado
• Autenticación personalizada: Pruebe los flujos de inicio y cierre de sesión de su sistema de identidad
• Cobertura de plataformas: Pruebe en todas las plataformas a las que está dirigido su juego (no solo en dispositivos Steam)
• Escenarios de red: Pruebe las transiciones entre sin conexión y en línea
• Rendimiento: Compruebe que las operaciones de sincronización no afectan al rendimiento del juego

​

Referencia de código de ejemplo

• Ubicación: PlayFabGameSaveSample-Windows
• Archivos clave:
  • SteamIntegration.cpp/.h - Detección de Steam Deck, configuración del registro, controladores de autenticación
  • GameSaveIntegrationUI.cpp/.h - Implementaciones de devoluciones de llamada de la interfaz de usuario para ambos enfoques

​

Documentación relacionada

• Guía de implementación del GDK de octubre de 2025
• Información general de Game Saves
• Inicio rápido de Game Saves