PlayFab 독립 실행형 SDK v1에서 Unified SDK v2로 마이그레이션

​

변경 사항 개요

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

​

프로젝트 구조 변경 사항

​

GDK 사용자용

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

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

​

프로젝트 참조 업데이트

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

​

GitHub/독립 실행형 사용자용

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

​

인증 및 엔터티 처리

​

토큰 관리 변경 사항

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

• 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 (네트워킹/음성)

​

초기화 변경 사항

PartyManager& partyManager = PartyManager::GetSingleton();
PartyError err = partyManager.Initialize("YOUR_PLAYFAB_TITLE_ID");

PartyManager& partyManager = PartyManager::GetSingleton();

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

PartyError err = partyManager.Initialize(&partyInitConfig);

​

로컬 사용자 생성 변경 사항

PartyLocalUser* localUser = nullptr;
PartyError err = partyManager.CreateLocalUser(entityId, titlePlayerEntityToken, &localUser);

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 작업 변경 사항

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

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. 성능 모니터링: 마이그레이션이 성능 문제를 도입하지 않도록 합니다.