> ## 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 독립 실행형 SDK v1에서 Unified SDK v2로 마이그레이션

> PlayFab 타이틀을 v1 독립 실행형 SDK에서 v2 Unified SDK로 마이그레이션합니다. 프로젝트 레이아웃, 인증, 토큰 관리 변경 사항을 다룹니다.

이 가이드는 이전 PlayFab v1 SDK에서 새로운 PlayFab Unified SDK v2로 마이그레이션하는 데 도움이 됩니다. Unified SDK는 이전에 분리되어 있던 SDK(Core, Services, Party, Multiplayer)를 향상된 상호 운용성과 간소화된 인증을 갖춘 단일 통합 솔루션으로 통합합니다.

## 변경 사항 개요

PlayFab Unified SDK v2는 몇 가지 주요 개선 사항을 도입합니다.

* **통합 아키텍처**: 모든 PlayFab 서비스(Core, Services, Party, Multiplayer, GameSave)가 단일 SDK로 통합됨
* **간소화된 인증**: 한 번의 로그인으로 엔터티 핸들을 통해 모든 PlayFab 서비스에 액세스
* **자동 토큰 관리**: 더 이상 수동 토큰 새로 고침이나 엔터티 ID 관리가 필요 없음
* **향상된 상호 운용성**: 서로 다른 PlayFab 서비스 간의 원활한 통신
* **간소화된 프로젝트 구조**: 여러 개의 별도 패키지 대신 단일 SDK 설치

## 프로젝트 구조 변경 사항

### GDK 사용자용

**레거시 레이아웃 (GDK 2504 및 이전):**

* 각 SDK 구성 요소에 대한 별도의 확장
* 개별 include 및 library 폴더: PlayFab.Services.Cpp, PlayFab.Party.Cpp, PlayFab.Multiplayer.Cpp
* 각 서비스는 GDK에서 고유한 ExtensionLibrary 이름을 가짐
* 서로 다른 PlayFab 서비스에 대해 GitHub에서 여러 번 다운로드가 필요

**새 레이아웃 (GDK 2510 이후):**

* 단일 통합 PlayFab SDK
* 하위 폴더(xbox, windows 등)가 있는 플랫폼별 구조
* 모든 헤더가 하나의 includes 폴더에 통합됨 (Core, Services, Multiplayer, Party, GameSave)
* 통합된 lib 폴더의 결합된 라이브러리

#### 프로젝트 참조 업데이트

전환 기간(GDK 2510) 동안 이전 SDK와 새 SDK가 공존합니다. 마이그레이션하려면:

1. **이전 참조 제거**: PlayFab.Services.Cpp, PlayFab.Party.Cpp 및 기타 개별 SDK 확장에 대한 참조를 삭제합니다.
2. **통합 참조 추가**: 새 PlayFab Unified SDK를 참조하거나 include/library 경로를 통합 위치로 업데이트합니다.
3. **미래에 대비**: Microsoft는 향후 GDK 릴리스(2026년까지 가능)에서 이전 폴더를 제거할 예정이므로 그에 따라 프로젝트 파일을 업데이트하세요.

### GitHub/독립 실행형 사용자용

* 여러 SDK 다운로드를 단일 통합 SDK 패키지로 교체
* 새로운 플랫폼별 폴더 구조를 사용하도록 프로젝트 경로 업데이트

## 인증 및 엔터티 처리

엔터티와 엔터티 토큰의 개념은 두 버전 모두에 존재하지만, v2에서는 사용 방법이 간소화되었습니다.

### 토큰 관리 변경 사항

**PlayFab 독립 실행형 SDK (v1) 접근 방식:**

* `PFAuthenticationGetEntityTokenAsync`를 사용한 수동 토큰 검색
* 토큰이 만료되면 수동 토큰 새로 고침
* 다른 서비스에 엔터티 ID와 토큰 문자열 전달(예: `partyManager.CreateLocalUser(entityId, titlePlayerEntityToken, &localUser)`)

**PlayFab Unified SDK (v2) 접근 방식:**

* Core SDK에 의한 자동 토큰 관리
* 만료 전 백그라운드 토큰 새로 고침
* 다른 서비스에 `PFEntityHandle`을 직접 전달(예: `partyManager.CreateLocalUser(entityHandle, &localUser)`)

### 인증 마이그레이션 단계

1. **수동 토큰 관리 제거**: PlayFab 토큰을 수동으로 검색하거나 확인하는 코드를 삭제합니다.
2. **엔터티 핸들 저장**: 로그인에서 얻은 `PFEntityHandle`을 유지하고 모든 PlayFab 서비스에서 사용합니다.
3. **서비스 호출 업데이트**: 엔터티 ID/토큰 매개변수를 엔터티 핸들로 대체합니다.
4. **재인증 처리**: 재인증 시나리오에 `PFAuthenticationReLogin*Async` API를 사용합니다.

## 구성 요소별 주요 API 변경 사항

### PlayFab Core

**마이그레이션 영향**: 최소한의 변경 필요

* 대부분의 Core 서비스 호출은 변경되지 않음
* 통합 SDK 헤더를 가리키도록 include 경로 업데이트

### PlayFab Services

**마이그레이션 영향**: 최소한의 변경 필요

* 대부분의 Service 호출은 변경되지 않음
* 통합 SDK 헤더를 가리키도록 include 경로 업데이트

### PlayFab Party (네트워킹/음성)

**마이그레이션 영향**: 소규모 변경 필요

#### 초기화 변경 사항

**v1 초기화:**

```cpp theme={null}
PartyManager& partyManager = PartyManager::GetSingleton();
PartyError err = partyManager.Initialize("YOUR_PLAYFAB_TITLE_ID");
```

**v2 초기화:**

```cpp theme={null}
PartyManager& partyManager = PartyManager::GetSingleton();

PartyInitializationConfiguration partyInitConfig = {};
partyInitConfig.titleId = "YOUR_PLAYFAB_TITLE_ID";
partyInitConfig.audioTaskQueue = nullptr;
partyInitConfig.networkingTaskQueue = nullptr;

PartyError err = partyManager.Initialize(&partyInitConfig);
```

#### 로컬 사용자 생성 변경 사항

**v1 접근 방식:**

```cpp theme={null}
PartyLocalUser* localUser = nullptr;
PartyError err = partyManager.CreateLocalUser(entityId, titlePlayerEntityToken, &localUser);
```

**v2 접근 방식:**

```cpp theme={null}
PartyLocalUser* localUser = nullptr;
PartyError err = partyManager.CreateLocalUser(entityHandle, &localUser);
```

#### Party 마이그레이션 단계

1. **초기화 업데이트**: 단순한 `PartyManager::Initialize()` 호출을 구성 구조체 접근 방식으로 대체합니다.
2. **토큰 검색 제거**: Party용 엔터티 ID/토큰을 수동으로 가져오는 코드를 삭제합니다.
3. **엔터티 핸들 전달**: 문자열 매개변수 대신 `PFEntityHandle`을 직접 사용합니다.
4. **토큰 새로 고침 로직 제거**: Party 토큰을 주기적으로 확인하거나 새로 고침하는 코드를 삭제합니다.
5. **종속성 업데이트**: `PartyManager::Initialize()` 전에 PlayFab Core가 초기화되었는지 확인합니다.
6. **XBOX 관련 호출 제거**: XBOX에서 `PartyXblManagerInitialize()`를 일반적인 `PartyInitialize()`로 대체합니다.

### PlayFab Multiplayer (Lobby 및 Matchmaking)

**마이그레이션 영향**: 소규모 변경 필요

핵심 개념(Lobby, 매치메이킹 Ticket)은 그대로 유지되지만, 함수는 이제 문자열 대신 엔터티 핸들을 기대합니다.

#### Lobby 작업 변경 사항

**v1 접근 방식:**

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

**v2 접근 방식:**

```cpp theme={null}
HRESULT hr = PFMultiplayerJoinLobbyWithEntityHandle(pfmHandle, entityHandle, connectionString, &joinConfig, nullptr, &lobby);
```

#### Multiplayer 마이그레이션 단계

1. **함수 호출 업데이트**: PlayFab ID와 엔터티 토큰 매개변수를 `PFEntityHandle`로 대체합니다.
2. **인증 단계 제거**: 별도의 "Authenticate Multiplayer" 호출을 삭제합니다.
3. **명시적 초기화**: `PFMultiplayerInitialize()`와 잠재적으로 `PFMultiplayerStartProcessing()`을 호출합니다.
4. **매치메이킹 업데이트**: 매치메이킹 티켓 생성에서 엔터티 핸들을 사용합니다.

## 일반 마이그레이션 체크리스트

### 코드 업데이트

* [ ] **include 경로 업데이트**: 통합 SDK include 디렉터리를 가리킵니다.
* [ ] **라이브러리 링크 업데이트**: 별도의 라이브러리 대신 통합 라이브러리를 연결합니다.
* [ ] **더 이상 사용되지 않는 함수 제거**: `PartyManager::CreateLocalUserWithEntityType`와 같은 제거된 함수에 대한 호출을 삭제합니다.
* [ ] **수동 토큰 관리 대체**: 토큰 캐싱 및 새로 고침 로직을 제거합니다.
* [ ] **초기화 순서 업데이트**: PlayFab Core가 다른 서비스보다 먼저 초기화되도록 합니다.

### 테스트 체크리스트

마이그레이션 후 각 하위 시스템을 확인합니다.

* [ ] **인증**: 로그인이 유효한 엔터티 핸들을 반환합니다.
* [ ] **Lobby 작업**: 로비 생성/참가가 올바르게 작동합니다.
* [ ] **Party 네트워킹**: 플레이어가 컴퓨터 간에 연결하고 통신할 수 있습니다.
* [ ] **오류 처리**: 모든 PlayFab 호출이 오류를 적절히 처리합니다.
* [ ] **다중 사용자 시나리오**: 해당하는 경우 여러 로컬 사용자가 작동합니다.

### 일반적인 문제와 해결책

**누락된 매개변수에 대한 컴파일러 오류**:

* 함수 시그니처가 `PFEntityHandle`을 요구하도록 변경되었는지 확인합니다.
* 문자열 ID 대신 엔터티 핸들을 전달하고 있는지 확인합니다.

**런타임 인증 실패**:

* 다른 서비스보다 먼저 PlayFab Core가 초기화되었는지 확인합니다.
* Party/Multiplayer에서 로컬 사용자를 만들기 전에 로그인이 완료되었는지 확인합니다.

**성능 저하**:

* 드물지만, v2가 성능이 중요한 코드 경로에 문제를 도입하지 않는지 확인합니다.

## 마이그레이션의 이점

### 코드 단순화

* **복잡성 감소**: v1의 서비스 분리를 위한 임시 해결 코드 제거
* **통합 오류 처리**: 모든 PlayFab 서비스가 일관된 오류 보고 사용
* **중앙 집중식 인증**: 모든 PlayFab 기능에 대한 하나의 로그인 흐름

### 향상된 상호 운용성

* **원활한 통합**: 새로운 PlayFab 기능 추가에 최소한의 설정 필요
* **더 나은 다중 사용자 지원**: 통합 SDK가 여러 로컬 사용자를 더 효과적으로 처리
* **일관된 엔터티 모델**: 모든 서비스에서 동일한 인증 접근 방식

### 미래 대비

* **활발한 개발**: v2는 활발히 유지 관리되는 버전
* **새 기능**: 향후 PlayFab 기능은 통합 SDK를 대상으로 함
* **장기 지원**: v1 SDK는 결국 더 이상 사용되지 않게 될 예정

## 다음 단계

1. **프로젝트 구조 업데이트**: 통합 SDK 레이아웃으로 마이그레이션합니다.
2. **인증 리팩터링**: 엔터티 핸들 기반 접근 방식을 구현합니다.
3. **철저히 테스트**: 모든 PlayFab 기능이 올바르게 작동하는지 검증합니다.
4. **코드 정리**: 더 이상 사용되지 않는 v1 임시 해결책과 수동 토큰 관리를 제거합니다.
5. **성능 모니터링**: 마이그레이션이 성능 문제를 도입하지 않도록 합니다.

추가 도움이 필요한 경우 특정 플랫폼에 대한 PlayFab Unified SDK 문서와 샘플을 참조하세요.


## Related topics

- [PlayFab SDK 제품](/ko/services/playfab/sdks/sdk-products.md)
- [2025년 10월 GDK를 사용한 Game Saves 구현](/ko/services/playfab/player-progression/game-saves/october-2025-gdk-changes.md)
- [Unity에서 Google 로그인에서 Google Play Games로 마이그레이션하기](/ko/services/playfab/identity/player-identity/platform-specific-authentication/google-play-games-sign-in-migration-details.md)
- [엔터티 마이그레이션 정보](/ko/services/playfab/live-service-management/game-configuration/entities/migration-information.md)
- [XDK 네트워킹을 XBOX GDK로 마이그레이션](/ko/build/console-features/networking/xdk-migration/index.md)