> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Guia abrangente para implementar o PlayFab Game Saves no Steam Deck com o GDK de outubro de 2025, incluindo autenticação, retornos de chamada de interface do usuário e estratégias de sincronização

<Info>
  Este guia aborda especificamente os requisitos de implementação do PlayFab Game Saves no Steam Deck com o GDK de outubro de 2025. Antes de implementar o suporte ao Steam Deck, verifique se você concluiu os requisitos básicos da [implementação com o GDK de outubro de 2025](/pt-BR/services/playfab/player-progression/game-saves/october-2025-gdk-changes).
</Info>

## Visão geral

A integração do Game Saves no Steam Deck pode ser implementada com diferentes níveis de complexidade, dependendo dos seus requisitos multiplataforma. Você pode escolher entre uma abordagem simplificada somente para a Steam ou uma integração completa com o ecossistema XBOX, com fluxos de autenticação mais complexos.

<Info>
  **Diferença crítica: comportamento de sincronização**: o Game Saves no Windows pode ser executado totalmente fora do processo e continuar sincronizando além do tempo de vida do jogo. No Steam Deck, o Game Saves é executado somente no processo. Isso significa que a sincronização dos salvamentos para quando o jogo é desligado, exigindo que os jogos adotem padrões de sincronização frequentes para evitar a perda de progresso não sincronizado. **Prática recomendada para todas as plataformas**: embora esses padrões de sincronização sejam obrigatórios para o Steam Deck, eles são altamente recomendados para todas as plataformas, especialmente dispositivos portáteis ou qualquer cenário em que possam ocorrer desligamentos repentinos (esgotamento da bateria, falhas do sistema, fechamento forçado).
</Info>

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

| Plataforma | Modo de sincronização | Sincronização após o desligamento | Padrão recomendado |
| - | - | - | - |
| **Windows PC** | Fora do processo | ✅ Continua após o desligamento do jogo | Sincronização frequente recomendada para maior confiabilidade |
| **Steam Deck** | No processo | ❌ Para quando o jogo é desligado | **Sincronização frequente obrigatória** |

**Recomendações universais de sincronização** (benéficas para todas as plataformas):

* 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

Antes de implementar o suporte ao Steam Deck, verifique se você:

1. **Concluiu a configuração do GDK de outubro de 2025**: siga o [guia de implementação com o GDK de outubro de 2025](/pt-BR/services/playfab/player-progression/game-saves/october-2025-gdk-changes)
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

O Steam Deck oferece duas abordagens de implementação com diferentes níveis de complexidade e recursos multiplataforma. O PlayFab Game Saves é valioso para a sincronização de salvamentos entre plataformas além do ecossistema da Steam; você precisará da integração com o XBOX Live (Abordagem 1) ou do seu próprio sistema personalizado de identidade de jogadores (Abordagem 2).

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

**Benefícios**:

* **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

**Complexidade**:

* **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

**Quando escolher**: jogos voltados para várias plataformas, incluindo consoles XBOX, títulos do XBOX Game Studios ou jogos que exigem a integração completa com o ecossistema do XBOX Live.

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

**Benefícios**:

* **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

**Complexidade**:

* **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

**Quando escolher**: jogos focados na Steam, jogos com sistemas de identidade personalizados existentes ou cenários de desenvolvimento em que a integração com o XBOX Live não é necessária nem desejada.

**OpenID Connect**: para a Abordagem 2, o PlayFab oferece suporte à autenticação OpenID Connect por meio da chamada à API `LoginWithOpenIdConnect`, permitindo a integração com provedores de identidade personalizados que dão suporte ao padrão OpenID Connect.

## Configuração comum (ambas as abordagens)

As etapas de configuração a seguir são necessárias independentemente da abordagem de implementação escolhida.

## 1. Requisitos de implantação de DLLs

O Steam Deck exige que todas as DLLs do Unified SDK sejam implantadas com o seu jogo:

**DLLs obrigatórias**:

* `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

**DLL opcional**:

* `PlayFabServices.dll`: serviços adicionais do PlayFab (recomendado)

**Estrutura de implantação no Steam Deck**:

```
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

```cpp theme={null}
// Initialize Steam API
bool steamAvailable = SteamAPI_Init();
```

### Detecção de plataforma

Implemente a detecção de plataforma no início da inicialização:

```cpp theme={null}
bool DetectSteamDeck() {
    if (!SteamAPI_Init()) {
        return false;
    }
    
    return SteamUtils()->IsSteamRunningOnSteamDeck();
}
```

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

<Info>
  **Requisito de interface do usuário do Steam Deck**: todos os retornos de chamada de interface do usuário do PlayFab Game Saves são **obrigatórios** no Steam Deck, independentemente da abordagem de implementação escolhida. Isso ocorre porque o Steam Deck não tem uma interface do usuário integrada disponível para as operações do Game Saves; portanto, seu aplicativo deve fornecer todas as caixas de diálogo.
</Info>

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

As implementações de identidade personalizada e do ecossistema XBOX exigem os mesmos retornos de chamada de interface do usuário do PlayFab Game Saves:

```cpp theme={null}
// 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 obrigatórias do Game Saves** (ambas as abordagens):

* **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

Esta abordagem oferece sincronização multiplataforma completa entre o Steam Deck, os consoles XBOX, o PC da Microsoft Store e outras plataformas habilitadas para XBOX. Escolha esta abordagem se o seu jogo for voltado para plataformas XBOX ou exigir a integração com o XBOX Live.

### Visão geral

**Pré-requisitos**:

* 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

O Steam Deck exige a configuração da área restrita do XBOX Live para testes em áreas restritas que não sejam de varejo:

```cpp theme={null}
// 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;
    }
}
```

**Detalhes da configuração**:

* **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

O Steam Deck exige dois conjuntos de manipuladores de eventos essenciais para a autenticação do XBOX:

#### A. Manipuladores de eventos Remote Connect

Tratam o fluxo de autenticação remota (exibição de código QR/URL):

```cpp theme={null}
// 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)

Tratam o prompt de entrada SPOP usado quando a conta de um usuário já está conectada em outro dispositivo:

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

O manipulador deve apresentar uma interface do usuário que permita ao jogador escolher uma ação (Sign In Here, Switch Account ou Cancel) e chamar `XUserPlatformSpopPromptComplete(operation, result)` com o resultado escolhido.

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

Além dos retornos de chamada de interface do usuário do Game Saves (Seção 3), a integração com o ecossistema XBOX exige:

* **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

Siga esta sequência de inicialização para a integração com o ecossistema XBOX:

```cpp theme={null}
// 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

O Steam Deck exige um tratamento especial de saída para limpar as credenciais do XBOX armazenadas:

```cpp theme={null}
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

Use esta lista de verificação para validar sua implementação do ecossistema XBOX:

* [ ] **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

Esta abordagem permite usar seu próprio sistema de identidade de jogadores sem a integração com o XBOX Live. Escolha esta abordagem se o seu jogo for focado na Steam ou se você tiver um sistema de identidade personalizado existente.

### Visão geral

**Pré-requisitos**:

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

**Benefícios**:

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

**Limitações**:

* É 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

Implemente seu próprio sistema de identidade para a autenticação de jogadores entre plataformas:

```cpp theme={null}
// 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

```cpp theme={null}
// 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

```cpp theme={null}
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

Use esta lista de verificação para validar sua implementação de identidade personalizada:

* [ ] **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

Para obter exemplos de implementação completos das duas abordagens, consulte o projeto de exemplo:

* **Local**: [PlayFabGameSaveSample-Windows](https://github.com/PlayFab/PlayFab-Samples/tree/master/Samples/All/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](/pt-BR/services/playfab/player-progression/game-saves/october-2025-gdk-changes)
* [Visão geral do Game Saves](/pt-BR/services/playfab/player-progression/game-saves/overview)
* [Início rápido do Game Saves](/pt-BR/services/playfab/player-progression/game-saves/quickstart)


## Related topics

- [Implementação do Game Saves com o GDK de outubro de 2025](/pt-BR/services/playfab/player-progression/game-saves/october-2025-gdk-changes.md)
- [Retornos de chamada de interface do Game Saves](/pt-BR/services/playfab/player-progression/game-saves/ui-callbacks.md)
- [Guia do desenvolvedor do Game Saves](/pt-BR/build/core-features/common/game-save/game-saves-developer-guide.md)
- [Visão geral do Game Saves](/pt-BR/services/playfab/player-progression/game-saves/overview.md)
- [Início rápido do Game Saves](/pt-BR/services/playfab/player-progression/game-saves/quickstart.md)