Skip to main content

빠른 시작: GDK

Microsoft Game Development Kit(GDK)용 PlayFab Services SDK를 시작하세요. 다음 단계에 따라 라이브러리를 프로젝트에 포함하고 기본 PlayFab 기능을 위한 샘플 코드를 시도해 보세요. 이 빠른 시작은 GDK를 사용해 첫 번째 PlayFab API 호출을 수행하는 데 도움이 됩니다. 계속하기 전에 빠른 시작: Game Manager의 단계를 완료했는지 확인하세요. 이 단계에서는 PlayFab 계정이 있고 PlayFab Game Manager에 익숙한지 확인합니다.

요구 사항

프로젝트 설정

다른 GDK 확장 라이브러리와 마찬가지로 프로젝트 속성을 통해 PlayFab Services SDK를 추가하세요. 프로젝트의 구성 속성에서 Gaming Desktop > General 아래에서 __Gaming Extension Libraries__를 선택합니다. 프롬프트에서 __PlayFab.Services.C__를 선택합니다.

초기화 및 로그인

헤더

포함된 모든 PlayFab 기능에 액세스하려면 __PFServices.h__를 포함하세요:

초기화

PlayFab 초기화에는 __PFServicesInitialize__와 PFServiceConfigCreateHandle 두 함수 호출이 필요합니다. 이 초기화의 결과가 __PFServiceConfigHandle__입니다. 이 핸들을 이후 로그인 호출에 제공하여 PlayFab 백엔드의 올바른 타이틀로 호출을 지시합니다.

로그인

__PFServiceConfigHandle__을 얻은 후에는 이를 사용해 플레이어 로그인 호출을 수행할 수 있습니다. GDK에서는 __PFAuthenticationLoginWithXUserAsync__를 사용합니다. 이 함수를 사용하면 __XUserHandle__을 사용해 플레이어를 PlayFab에 로그인할 수 있습니다. XUserHandle 획득 및 관리에 대한 자세한 내용은 User Identity and XUser를 참조하세요. 로그인 호출을 수행한 후 __XAsyncGetStatus__로 호출 상태를 확인할 수 있습니다. 상태는 __E_PENDING__으로 시작하여 호출이 성공적으로 완료된 후 __S_OK__로 변경됩니다. 어떤 이유로 호출이 실패하면 상태에 해당 실패가 반영됩니다. 모든 PlayFab Services 호출에 대한 오류 처리는 이 방식으로 작동합니다. S_OK 결과와 함께 __PFEntityHandle__을 다시 받게 됩니다. 이 핸들을 사용해 로그인된 플레이어로서 이후의 PlayFab 호출을 수행합니다. 여기에는 해당 플레이어로 PlayFab 서비스에 인증하는 데 필요한 모든 자료가 포함됩니다.

일시 중단 및 재개 처리

GDK 게임은 예를 들어 Quick Resume을 통해 오랫동안 일시 중단될 수 있습니다. 일시 중단 중에 엔터티 토큰이 만료되면 SDK가 재개 시 이를 감지하고 게임에 알립니다. 필요할 때 다시 인증하고 서비스를 다시 연결할 수 있도록 게임의 수명 주기 초기에 TokenExpiredHandler를 등록해야 합니다. 전체 세부 정보는 토큰 만료 처리를 참조하세요.

서비스 호출

플레이어를 로그인한 후에는 이제 PlayFab 백엔드로 호출을 수행할 수 있습니다. 다음은 현재 플레이어에 대해 PlayFab에 저장된 파일을 가져오는 호출의 예입니다.

EntityKey 가져오기

일부 PlayFab 호출에 유용할 수 있는 한 가지는 플레이어의 __PFEntityKey__를 아는 것입니다. __PFEntityToken__이 있으면 __PFEntityGetEntityKey__로 __PFEntityKey__를 검색할 수 있습니다.

GetFiles 호출

모든 PlayFab 호출은 요청 객체를 준비하고, (로그인의 __PFEntityHandle__을 사용해) 호출을 수행하고, 응답을 받을 객체를 생성한 다음, GetResult 함수를 호출해 새로 생성된 컨테이너를 채우는 유사한 패턴을 따릅니다.

정리

게임이 종료될 준비가 되었거나 다른 이유로 PlayFab을 정리해야 하는 경우, 열려 있는 모든 핸들을 닫고 __PFServicesUninitializeAsync__를 호출해야 합니다.

비동기 API 패턴

GDK용 PlayFab Services SDK는 GDK에서 구현된 비동기 프로그래밍 모델을 따릅니다. 이 프로그래밍 모델은 XAsync 라이브러리에서 제공하는 Tasks와 Task Queues 사용을 포함합니다. 이 모델은 다른 GDK 함수 및 확장(예: XBOX Services API)과 일관성이 있습니다. 약간의 복잡성을 도입하지만, 비동기 작업에 대한 높은 수준의 제어도 제공합니다. 이 예제는 __PFDataGetFilesAsync__에 대한 비동기 호출을 수행하는 방법을 보여줍니다.

오류 처리

완료된 XAsync 작업은 HTTP 상태 코드를 반환합니다. 오류 상태 코드는 XAsyncGetStatus() 또는 PF*Get() API 중 하나를 호출할 때 HTTP_E_STATUS_NOT_FOUND와 같은 실패 HRESULT로 나타납니다. 서비스에서 반환된 자세한 오류 메시지를 보려면 디버깅에 대한 다음 섹션을 참조하세요. 이러한 자세한 오류 메시지는 개발 중에 PlayFab 서비스가 클라이언트의 요청에 어떻게 반응하는지 더 잘 이해하는 데 유용할 수 있습니다.

디버깅

PlayFab Services SDK에서 결과를 확인하고 호출을 디버그하는 가장 쉬운 방법은 디버그 추적을 활성화하는 것입니다. 디버그 추적을 활성화하면 디버거 출력 창에서 결과를 확인하고 게임의 자체 로그에 결과를 후킹할 수 있습니다.

참조

API 참조 문서
마지막 수정일 2026년 9월 1일