> ## 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.

# PlayFab Game Saves용 Steam Deck 구현 가이드

> 인증, UI 콜백, 동기화 전략을 포함한 2025년 10월 GDK로 Steam Deck에서 PlayFab Game Saves를 구현하기 위한 포괄적인 가이드

<Info>
  이 가이드는 2025년 10월 GDK를 사용한 PlayFab Game Saves의 Steam Deck 구현 요구 사항을 구체적으로 다룹니다. Steam Deck 지원을 구현하기 전에 기본 [2025년 10월 GDK 구현](/services/playfab/player-progression/game-saves/october-2025-gdk-changes) 요구 사항을 완료했는지 확인하세요.
</Info>

## 개요

Steam Deck Game Saves 통합은 크로스 플랫폼 요구 사항에 따라 다양한 수준의 복잡성으로 구현할 수 있습니다. 단순화된 Steam 전용 접근 방식이나 더 복잡한 인증 흐름을 가진 전체 XBOX 생태계 통합 중에서 선택할 수 있습니다.

<Info>
  **중요한 차이 - 동기화 동작**: Windows의 Game Saves는 완전히 프로세스 외에서 실행되며 게임의 수명 이후에도 동기화를 계속할 수 있습니다. Steam Deck에서는 Game Saves가 프로세스 내에서만 실행됩니다. 이는 게임이 종료되면 세이브 동기화가 중단됨을 의미하며, 동기화되지 않은 진행 상황을 잃지 않으려면 게임이 빈번한 동기화 패턴을 채택해야 합니다. **모든 플랫폼에 대한 모범 사례**: 이러한 동기화 패턴은 Steam Deck에 필수적이지만, 모든 플랫폼, 특히 휴대용 디바이스나 갑작스러운 종료가 발생할 수 있는 시나리오(배터리 소진, 시스템 충돌, 강제 종료 이벤트)에 매우 권장됩니다.
</Info>

## 동기화 엔진 동작 차이점

| 플랫폼            | 동기화 모드 | 종료 후 동기화      | 권장 패턴              |
| -------------- | ------ | ------------- | ------------------ |
| **Windows PC** | 프로세스 외 | ✅ 게임 종료 후 계속됨 | 신뢰성을 위해 빈번한 동기화 권장 |
| **Steam Deck** | 프로세스 내 | ❌ 게임 종료 시 중단됨 | **빈번한 동기화 필수**     |

**범용 동기화 권장 사항** (모든 플랫폼에 유용):

* 세이브 데이터를 자주 동기화(예: 각 레벨, 체크포인트 또는 상당한 진행 후)
* "게임 종료" 확인을 표시하기 전에 항상 동기화
* 게임플레이 전환 중 백그라운드 동기화 고려
* 종료 전 완료를 보장하기 위한 동기화 진행 표시기 구현
* 배터리 소진이나 갑작스러운 종료가 흔한 휴대용 디바이스에 특히 중요

## 사전 요구 사항

Steam Deck 지원을 구현하기 전에 다음을 확인하세요:

1. **2025년 10월 GDK 설정 완료**: [2025년 10월 GDK 구현 가이드](/services/playfab/player-progression/game-saves/october-2025-gdk-changes)를 따르세요
2. **Steam API 통합**: 기본 Steam API 초기화 및 Steam Deck 감지
3. **통합 접근 방식 선택**: XBOX 생태계 또는 사용자 지정 ID 통합 중에서 결정(아래 참조)
4. **모든 필요한 DLL**: Unified SDK DLL이 Steam 빌드와 함께 배포되어야 함

## 구현 접근 방식

Steam Deck은 서로 다른 복잡성 수준과 크로스 플랫폼 기능을 가진 두 가지 구현 접근 방식을 제공합니다. PlayFab Game Saves는 Steam 생태계 이외의 크로스 플랫폼 세이브 동기화에 유용합니다 - XBOX Live 통합(접근 방식 1) 또는 자체 사용자 지정 플레이어 ID 시스템(접근 방식 2) 중 하나가 필요합니다.

### 접근 방식 1: XBOX 생태계 통합 (권장)

**이점**:

* **완전한 크로스 플랫폼 동기화**: Steam Deck, XBOX 콘솔, Microsoft Store PC 및 기타 XBOX 지원 플랫폼 간에 세이브 데이터가 동기화됨
* **XBOX Live 통합**: 플레이어가 XBOX gamertag를 사용하고 XBOX 소셜 기능에 액세스할 수 있음
* **통합된 플레이어 ID**: 모든 플랫폼에서 동일한 플레이어 프로필
* **검증된 인증**: XBOX Live의 성숙한 인증 인프라 활용
* **XBOX Game Studios 호환성**: XBOX 퍼스트 파티 및 파트너 스튜디오를 위한 원활한 통합

**복잡성**:

* **복잡한 인증**: 사용자 지정 XUser 이벤트 핸들러 및 UI 콜백 필요
* **개발 샌드박스 설정**: 비소매 테스트 환경에 필요
* **관리자 권한**: 샌드박스 설정 중 레지스트리 수정에 필요
* **추가 UI 구현**: QR 코드 인증 및 gamertag 선택 대화 상자

**선택 시기**: XBOX 콘솔을 포함한 여러 플랫폼을 대상으로 하는 게임, XBOX Game Studios 타이틀 또는 완전한 XBOX Live 생태계 통합이 필요한 게임.

### 접근 방식 2: 사용자 지정 ID 구현 (대안)

**이점**:

* **잠재적으로 감소된 로그인 복잡성**: XBOX 사용자 인증 불필요
* **레지스트리 구성 없음**: 샌드박스 설정 불필요
* **XUser API 없음**: 복잡한 이벤트 핸들러 제거
* **사용자 지정 ID 유연성**: 자체 크로스 플랫폼 플레이어 ID 시스템 구현

**복잡성**:

* **수동 플레이어 관리**: 자체 크로스 플랫폼 플레이어 ID 시스템을 구현해야 함
* **제한된 생태계 통합**: XBOX Live 소셜 기능이나 기존 XBOX 플레이어 기반에 액세스할 수 없음
* **플랫폼 브리징**: 다른 플랫폼 간에 플레이어를 연결하기 위한 사용자 지정 솔루션 필요
* **추가 ID 인프라**: 타사 ID 시스템을 구축하거나 통합해야 함

**선택 시기**: Steam 중심 게임, 기존 사용자 지정 ID 시스템이 있는 게임, 또는 XBOX Live 통합이 필요하거나 원하지 않는 개발 시나리오.

**OpenID Connect**: 접근 방식 2의 경우, PlayFab은 `LoginWithOpenIdConnect` API 호출을 통해 OpenID Connect 인증을 지원하며, OpenID Connect 표준을 지원하는 사용자 지정 ID 공급자와 통합할 수 있습니다.

## 공통 설정 (두 접근 방식 모두)

다음 설정 단계는 선택한 구현 접근 방식과 관계없이 필수입니다.

## 1. DLL 배포 요구 사항

Steam Deck은 모든 Unified SDK DLL을 게임과 함께 배포해야 합니다:

**필수 DLL**:

* `libHttpClient.dll` - HTTP 작업
* `PlayFabCore.dll` - 인증 및 핵심 서비스
* `PlayFabGameSave.dll` - Game Saves 기능
* `xgameruntime.dll` - 핵심 SDK 기능 및 XBOX 로그인

**선택적 DLL**:

* `PlayFabServices.dll` - 추가 PlayFab 서비스 (권장)

**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. Steam 통합 사전 요구 사항

### Steam API 통합

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

### 플랫폼 감지

초기화 초기에 플랫폼 감지를 구현합니다:

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

## 3. UI 콜백 구현

<Info>
  **Steam Deck UI 요구 사항**: 선택한 구현 접근 방식과 관계없이 Steam Deck에서는 모든 PlayFab Game Saves UI 콜백이 **필수**입니다. 이는 Steam Deck에 Game Saves 작업을 위한 내장 UI가 없기 때문이며, 따라서 애플리케이션이 모든 UI 대화 상자를 제공해야 합니다.
</Info>

### Game Saves UI 콜백 (두 접근 방식 모두 필수)

사용자 지정 ID 및 XBOX 생태계 구현 모두 동일한 PlayFab Game Saves UI 콜백이 필요합니다:

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

**필수 Game Saves UI 대화 상자** (두 접근 방식 모두):

* **진행률 대화 상자**: 세이브 작업 중 동기화 진행 상황 표시
* **오류 처리**: 동기화 실패 메시지 및 재시도 옵션 표시
* **충돌 해결**: 디바이스 간 세이브 충돌 처리
* **디바이스 경합**: 여러 디바이스 액세스 시나리오 처리
* **저장소 관리**: 저장소 할당량 문제에 대해 사용자에게 알림

***

## 접근 방식 1: XBOX 생태계 통합 - 전체 구현

이 접근 방식은 Steam Deck, XBOX 콘솔, Microsoft Store PC 및 기타 XBOX 지원 플랫폼 간의 완전한 크로스 플랫폼 동기화를 제공합니다. 게임이 XBOX 플랫폼을 대상으로 하거나 XBOX Live 통합이 필요한 경우 이 접근 방식을 선택하세요.

### 개요

**사전 요구 사항**:

* 공통 설정 완료 (위의 섹션 1-3)
* 테스트를 위한 개발 샌드박스 액세스
* 레지스트리 구성을 위한 관리자 권한 (개발/테스트만)

### 1. 레지스트리 구성

Steam Deck은 비소매 샌드박스 테스트를 위해 XBOX Live 샌드박스 구성이 필요합니다:

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

**구성 세부 정보**:

* **키**: `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\XboxLive\Sandbox`
* **값**: 개발 샌드박스 ID (예: "XDKS.1")
* **타이밍**: XBOX Live 서비스가 초기화되기 전에 설정해야 함
* **권한**: 관리자 액세스 필요
* **사용**: 비소매 샌드박스(개발/테스트 환경)에서 테스트할 때만 필요

### 2. XUser 플랫폼 이벤트 핸들러

Steam Deck은 XBOX 인증을 위해 두 가지 중요한 이벤트 핸들러 세트가 필요합니다:

#### A. Remote Connect 이벤트 핸들러

원격 인증 흐름(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. SPOP (Sign-in Prompt) 이벤트 핸들러

사용자 계정이 다른 디바이스에 이미 로그인되어 있을 때 사용되는 SPOP 로그인 프롬프트를 처리합니다:

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

핸들러는 플레이어가 액션(여기서 로그인, 계정 전환 또는 취소)을 선택할 수 있는 UI를 제시하고 선택한 결과와 함께 `XUserPlatformSpopPromptComplete(operation, result)`를 호출해야 합니다.

### 3. 인증 UI 구현

Game Saves UI 콜백(섹션 3) 외에 XBOX 생태계 통합에는 다음이 필요합니다:

* **Remote Connect 대화 상자**: 사용자가 다른 디바이스에서 인증할 수 있도록 QR 코드 및 URL 표시
* **SPOP Prompt 대화 상자**: 사용자가 XBOX gamertag를 선택/확인할 수 있게 함

### 4. 초기화 시퀀스

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. 로그아웃 구현

Steam Deck은 저장된 XBOX 자격 증명을 지우기 위해 특별한 로그아웃 처리가 필요합니다:

```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. 테스트 체크리스트

이 체크리스트를 사용하여 XBOX 생태계 구현을 검증하세요:

* [ ] **인증 흐름**: 원격 연결(QR 코드/URL) 인증 테스트
* [ ] **UI 콜백**: 모든 Game Saves UI 대화 상자가 올바르게 표시되는지 확인
* [ ] **SPOP 프롬프트**: gamertag 선택 및 확인 테스트
* [ ] **자격 증명 지속성**: 앱 재시작 시 로그인 지속성 테스트
* [ ] **로그아웃**: 로그아웃 시 자격 증명 정리가 제대로 이루어지는지 확인
* [ ] **동기화 동작**: 빈번한 동기화 패턴 및 종료 전 동기화 테스트
* [ ] **데이터 손실 방지**: 강제 종료 시나리오 중 최소한의 진행 손실 확인
* [ ] **크로스 플랫폼 동기화**: Steam Deck, XBOX 콘솔, Microsoft Store PC 간 세이브 동기화 테스트
* [ ] **레지스트리 구성**: 개발 환경에서 샌드박스 구성이 작동하는지 확인
* [ ] **XUser 이벤트 핸들러**: Remote Connect 및 SPOP 핸들러가 올바르게 작동하는지 확인

***

## 접근 방식 2: 사용자 지정 ID 구현 - 전체 구현

이 접근 방식은 XBOX Live 통합 없이 자체 플레이어 ID 시스템을 사용할 수 있게 해줍니다. 게임이 Steam 중심이거나 기존 사용자 지정 ID 시스템이 있는 경우 이 접근 방식을 선택하세요.

### 개요

**사전 요구 사항**:

* 공통 설정 완료 (위의 섹션 1-3)
* 프로덕션 사용을 위한 사용자 지정 플레이어 ID 시스템

**이점**:

* XBOX 인증 불필요
* 레지스트리 구성 불필요
* 관리자 권한 불필요
* 더 간단한 UI(QR 코드 또는 gamertag 선택 없음)

**제한 사항**:

* 자체 크로스 플랫폼 플레이어 ID를 구현해야 함
* XBOX Live 소셜 기능 없음
* 사용자 지정 플랫폼 브리징 솔루션 필요

### 1. 사용자 지정 ID 인증

크로스 플랫폼 플레이어 인증을 위해 자체 ID 시스템을 구현합니다:

```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. 초기화 시퀀스

```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. 로그아웃 구현

```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. 테스트 체크리스트

이 체크리스트를 사용하여 사용자 지정 ID 구현을 검증하세요:

* [ ] **사용자 지정 ID 시스템**: 사용자 지정 플레이어 인증 및 ID 시스템 테스트
* [ ] **PlayFab 인증**: LoginWithOpenIdConnect(OpenID Connect 사용 시) 또는 사용자 지정 인증 방법을 사용하여 PlayFab 로그인 테스트
* [ ] **크로스 플랫폼 Game Saves 동기화**: 모든 대상 플랫폼에서 세이브 동기화 테스트
* [ ] **UI 콜백**: 모든 Game Saves UI 대화 상자가 올바르게 표시되는지 확인
* [ ] **충돌 해결**: 서로 다른 플랫폼의 디바이스 간 세이브 충돌 테스트
* [ ] **동기화 동작**: 빈번한 동기화 패턴 및 종료 전 동기화 테스트
* [ ] **데이터 손실 방지**: 강제 종료 시나리오 중 최소한의 진행 손실 확인
* [ ] **사용자 지정 인증**: ID 시스템의 로그인/로그아웃 흐름 테스트
* [ ] **플랫폼 범위**: 게임이 대상으로 하는 모든 플랫폼에서 테스트(Steam 디바이스뿐만 아니라)
* [ ] **네트워크 시나리오**: 오프라인/온라인 전환 테스트
* [ ] **성능**: 동기화 작업이 게임플레이 성능에 영향을 미치지 않는지 확인

***

## 샘플 코드 참조

두 접근 방식에 대한 전체 구현 예제는 샘플 프로젝트를 참조하세요:

* **위치**: [PlayFabGameSaveSample-Windows](https://github.com/PlayFab/PlayFab-Samples/tree/master/Samples/All/PlayFabGameSaveSample-Windows)
* **주요 파일**:
  * `SteamIntegration.cpp/.h` - Steam Deck 감지, 레지스트리 설정, 인증 핸들러
  * `GameSaveIntegrationUI.cpp/.h` - 두 접근 방식에 대한 UI 콜백 구현

***

## 관련 문서

* [2025년 10월 GDK 구현 가이드](/services/playfab/player-progression/game-saves/october-2025-gdk-changes)
* [Game Saves 개요](/services/playfab/player-progression/game-saves/overview)
* [Game Saves 빠른 시작](/services/playfab/player-progression/game-saves/quickstart)


## Related topics

- [PlayFab Game Saves용 계정 연결 전략](/ko/services/playfab/player-progression/game-saves/linking.md)
- [2025년 10월 GDK를 사용한 Game Saves 구현](/ko/services/playfab/player-progression/game-saves/october-2025-gdk-changes.md)
- [Game Saves UI 콜백](/ko/services/playfab/player-progression/game-saves/ui-callbacks.md)
- [Steam 포팅 가이드 개요](/ko/build/steam-porting-guide/overview.md)
- [XBOX GDK로의 포팅 가이드](/ko/home/build-first-title/porting-guides.md)