Guia de implementação do PlayFab Game Saves no Steam Deck

​

Visão geral

​

Diferenças de comportamento do mecanismo de sincronização

• Sincronize os dados salvos com frequência (por exemplo, após cada nível, checkpoint ou progresso significativo)
• Sempre sincronize antes de exibir as confirmações de “sair do jogo”
• Considere a sincronização em segundo plano durante as transições de jogabilidade
• Implemente indicadores de progresso da sincronização para garantir a conclusão antes do desligamento
• Especialmente importante para dispositivos portáteis, em que o esgotamento da bateria ou desligamentos repentinos são comuns

​

Pré-requisitos

1. Concluiu a configuração do GDK de outubro de 2025: siga o guia de implementação com o GDK de outubro de 2025
2. Integrou a API da Steam: inicialização básica da API da Steam e detecção do Steam Deck
3. Escolheu a abordagem de integração: decida entre a integração com o ecossistema XBOX ou com uma identidade personalizada (veja abaixo)
4. Tem todas as DLLs necessárias: as DLLs do Unified SDK devem ser implantadas com o seu build da Steam

​

Abordagens de implementação

​

Abordagem 1: integração com o ecossistema XBOX (recomendada)

• Sincronização multiplataforma completa: os dados salvos são sincronizados entre o Steam Deck, os consoles XBOX, o PC da Microsoft Store e outras plataformas habilitadas para XBOX
• Integração com o XBOX Live: os jogadores usam seu gamertag do XBOX e podem acessar os recursos sociais do XBOX
• Identidade de jogador unificada: o mesmo perfil de jogador em todas as plataformas
• Autenticação comprovada: aproveita a infraestrutura de autenticação madura do XBOX Live
• Compatibilidade com o XBOX Game Studios: integração contínua para estúdios first-party e parceiros do XBOX

• Autenticação complexa: manipuladores de eventos XUser personalizados e retornos de chamada de interface do usuário são necessários
• Configuração da área restrita de desenvolvimento: necessária para ambientes de teste que não sejam de varejo
• Privilégios de administrador: necessários para modificações do Registro durante a configuração da área restrita
• Implementação adicional de interface do usuário: autenticação por código QR e caixas de diálogo de seleção de gamertag

​

Abordagem 2: implementação de identidade personalizada (alternativa)

• Complexidade de entrada potencialmente reduzida: nenhuma autenticação de usuário do XBOX é necessária
• Sem configuração do Registro: nenhuma configuração de área restrita é necessária
• Sem APIs XUser: elimina manipuladores de eventos complexos
• Flexibilidade de identidade personalizada: implemente seu próprio sistema de identidade de jogadores multiplataforma

• Gerenciamento manual de jogadores: é preciso implementar seu próprio sistema de identidade de jogadores multiplataforma
• Integração limitada ao ecossistema: sem acesso aos recursos sociais do XBOX Live nem à base de jogadores existente do XBOX
• Ponte entre plataformas: exige soluções personalizadas para conectar jogadores entre plataformas diferentes
• Infraestrutura de identidade adicional: é necessário criar ou integrar sistemas de identidade de terceiros

​

Configuração comum (ambas as abordagens)

​

1. Requisitos de implantação de DLLs

• libHttpClient.dll: operações HTTP
• PlayFabCore.dll: autenticação e serviços principais
• PlayFabGameSave.dll: funcionalidade do Game Saves
• xgameruntime.dll: recursos principais do SDK e entrada com o XBOX

• PlayFabServices.dll: serviços adicionais do 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. Pré-requisitos de integração com a Steam

​

Integração com a API da Steam

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

​

Detecção de plataforma

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

​

3. Implementação dos retornos de chamada de interface do usuário

​

Retornos de chamada de interface do usuário do Game Saves (obrigatórios para ambas as abordagens)

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

• Caixas de diálogo de progresso: mostram o progresso da sincronização durante as operações de salvamento
• Tratamento de erros: exibe mensagens de falha de sincronização e opções de nova tentativa
• Resolução de conflitos: trata os conflitos de salvamento entre dispositivos
• Disputa de dispositivos: trata cenários de acesso a partir de vários dispositivos
• Gerenciamento de armazenamento: notifica os usuários sobre problemas de cota de armazenamento

​

Abordagem 1: integração com o ecossistema XBOX - implementação completa

​

Visão geral

• Configuração comum concluída (seções 1 a 3 acima)
• Acesso à área restrita de desenvolvimento para testes
• Privilégios de administrador para a configuração do Registro (somente desenvolvimento/teste)

​

1. Configuração do 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;
    }
}

• Chave: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\XboxLive\Sandbox
• Valor: ID da área restrita de desenvolvimento (por exemplo, “XDKS.1”)
• Momento: deve ser definido antes da inicialização dos serviços do XBOX Live
• Privilégios: exige acesso de administrador
• Uso: necessário somente para testes em áreas restritas que não sejam de varejo (ambientes de desenvolvimento/teste)

​

2. Manipuladores de eventos de plataforma XUser

​

A. Manipuladores de eventos Remote Connect

// 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. Manipuladores de eventos SPOP (prompt de entrada)

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

​

3. Implementação da interface do usuário de autenticação

• Caixa de diálogo Remote Connect: exibe o código QR e a URL para que os usuários se autentiquem em outro dispositivo
• Caixa de diálogo de prompt SPOP: permite que os usuários selecionem/confirmem seu gamertag do XBOX

​

4. Sequência de inicialização

// 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. Implementação da saída

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 verificação de testes

• Fluxo de autenticação: teste a autenticação Remote Connect (código QR/URL)
• Retornos de chamada de interface do usuário: verifique se todas as caixas de diálogo do Game Saves são exibidas corretamente
• Prompts SPOP: teste a seleção e a confirmação do gamertag
• Persistência de credenciais: teste a persistência da entrada entre reinicializações do aplicativo
• Saída: verifique a limpeza adequada das credenciais ao sair
• Comportamento de sincronização: teste os padrões de sincronização frequente e a sincronização antes do desligamento
• Prevenção de perda de dados: verifique se o progresso perdido é mínimo em cenários de fechamento forçado
• Sincronização multiplataforma: teste a sincronização de salvamentos entre o Steam Deck, os consoles XBOX e o PC da Microsoft Store
• Configuração do Registro: verifique se a configuração da área restrita funciona em ambientes de desenvolvimento
• Manipuladores de eventos XUser: confirme se os manipuladores Remote Connect e SPOP funcionam corretamente

​

Abordagem 2: implementação de identidade personalizada - implementação completa

​

Visão geral

• Configuração comum concluída (seções 1 a 3 acima)
• Sistema personalizado de identidade de jogadores para uso em produção

• Nenhuma autenticação do XBOX é necessária
• Nenhuma configuração do Registro é necessária
• Nenhum privilégio de administrador é necessário
• Interface do usuário mais simples (sem código QR ou seleção de gamertag)

• É preciso implementar sua própria identidade de jogadores multiplataforma
• Sem recursos sociais do XBOX Live
• Exige soluções personalizadas de ponte entre plataformas

​

1. Autenticação com identidade 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. Sequência de inicialização

// 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. Implementação da saída

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 verificação de testes

• Sistema de identidade personalizado: teste a autenticação de jogadores e o sistema de identidade personalizados
• Autenticação do PlayFab: teste o login no PlayFab usando LoginWithOpenIdConnect (se usar o OpenID Connect) ou o método de autenticação personalizado
• Sincronização multiplataforma do Game Saves: teste a sincronização de salvamentos em todas as plataformas de destino
• Retornos de chamada de interface do usuário: verifique se todas as caixas de diálogo do Game Saves são exibidas corretamente
• Resolução de conflitos: teste os conflitos de salvamento entre dispositivos em plataformas diferentes
• Comportamento de sincronização: teste os padrões de sincronização frequente e a sincronização antes do desligamento
• Prevenção de perda de dados: verifique se o progresso perdido é mínimo em cenários de fechamento forçado
• Autenticação personalizada: teste os fluxos de login/logout do seu sistema de identidade
• Cobertura de plataformas: teste em todas as plataformas para as quais seu jogo é voltado (não apenas dispositivos Steam)
• Cenários de rede: teste as transições entre offline e online
• Desempenho: verifique se as operações de sincronização não afetam o desempenho do jogo

​

Referência de código de exemplo

• Local: PlayFabGameSaveSample-Windows
• Arquivos principais:
  • SteamIntegration.cpp/.h: detecção do Steam Deck, configuração do Registro, manipuladores de autenticação
  • GameSaveIntegrationUI.cpp/.h: implementações dos retornos de chamada de interface do usuário para as duas abordagens

​

Documentação relacionada

• Guia de implementação com o GDK de outubro de 2025
• Visão geral do Game Saves
• Início rápido do Game Saves