빠른 시작: GDK
Microsoft 게임 개발 키트(GDK)용 PlayFab 서비스 SDK로 시작하세요. 다음 단계에 따라 프로젝트에 라이브러리를 포함하고 기본 PlayFab 기능에 대한 샘플 코드를 사용해 보세요.
이 빠른 시작은 GDK를 사용하여 첫 번째 PlayFab API 호출을 만드는 데 도움이 됩니다. 계속하기 전에 PlayFab 계정이 있고 PlayFab 게임 관리자에 대해 잘 알고 있는지 확인하는 빠른 시작: 게임 관리자의 단계를 완료했는지 확인하세요.
요구 사항
- PlayFab 개발자 계정
- Visual Studio 2019 또는 2022가 설치되었습니다.
- GDK 개발을 위한 Visual Studio 요구 사항에 대한 자세한 내용은 SDK 및 도구 요구 사항을 참조하세요.
프로젝트 설정
다른 GDK 확장 라이브러리와 마찬가지로 프로젝트 속성을 통해 PlayFab 서비스 SDK를 추가합니다. 프로젝트의 구성 속성에 있는 Gaming Desktop>General에서 Gaming Extension Libraries를 선택합니다. 프롬프트에서 PlayFab.Services.C를 확인합니다.
초기화 및 로그인
헤더
포함된 모든 PlayFab 기능에 액세스하려면 PFServices.h를 포함합니다.
#include <playfab/services/PFServices.h>
초기화
PlayFab 초기화에는 두 가지 함수 호출(PFServicesInitialize 및 PFServiceConfigCreateHandle)이 필요합니다. 이 초기화의 결과는 PFServiceConfigHandle입니다. 후속 로그인 호출에 이 핸들을 제공하여 호출을 PlayFab 백엔드의 올바른 제목으로 지정합니다.
HRESULT hr = PFServicesInitialize(nullptr); // Add your own error handling when FAILED(hr) == true
PFServiceConfigHandle serviceConfigHandle{ nullptr };
hr = PFServiceConfigCreateHandle(
"https://ABCDEF.playfabapi.com", // PlayFab API endpoint - obtained in the Game Manager
"ABCDEF", // PlayFab Title id - obtained in the Game Manager
&serviceConfigHandle);
로그인
PFServiceConfigHandle이 있으면 이를 사용하여 플레이어 로그인 호출을 할 수 있습니다. GDK에서 PFAuthenticationLoginWithXUserAsync를 사용합니다. 이 기능을 사용하면 XUserHandle을 사용하여 플레이어를 PlayFab에 로그인할 수 있습니다. XUserHandle 획득 및 관리에 대한 자세한 내용은 사용자 ID 및 XUser를 참조하세요.
로그인 호출을 한 후 XAsyncGetStatus로 호출 상태를 확인할 수 있습니다. 상태는 E_PENDING으로 시작하고 통화가 성공적으로 완료되면 S_OK로 변경됩니다. 어떤 이유로 호출이 실패하면 상태에 해당 실패가 반영됩니다. 모든 PlayFab 서비스 호출에 대한 오류 처리는 이 방식으로 작동합니다.
S_OK 결과와 함께 PFEntityHandle을 반환합니다. 이 핸들을 사용하여 로그인한 플레이어로 후속 PlayFab 호출을 수행합니다. 여기에는 해당 플레이어로 PlayFab 서비스를 인증하는 데 필요한 모든 자료가 포함됩니다.
PFAuthenticationLoginWithXUserRequest request{};
request.createAccount = true;
request.user = userHandle; // An XUserHandle obtained from XUserAddAsync
XAsyncBlock async{};
HRESULT hr = PFAuthenticationLoginWithXUserAsync(serviceConfigHandle, &request, &async); // Add your own error handling when FAILED(hr) == true
hr = XAsyncGetStatus(&async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage
std::vector<char> loginResultBuffer;
PFAuthenticationLoginResult const* loginResult;
size_t bufferSize;
hr = PFAuthenticationLoginWithXUserGetResultSize(&async, &bufferSize);
loginResultBuffer.resize(bufferSize);
PFEntityHandle entityHandle{ nullptr };
hr = PFAuthenticationLoginWithXUserGetResult(&async, &entityHandle, loginResultBuffer.size(), loginResultBuffer.data(), &loginResult, nullptr);
서비스 호출
플레이어를 로그인한 후 이제 PlayFab 백 엔드를 호출할 수 있습니다. 다음은 현재 플레이어에 대해 PlayFab에 저장된 파일을 가져오기 위한 호출의 예입니다.
EntityKey 가져오기
PlayFab에 대한 일부 호출에 유용할 수 있는 한 가지는 플레이어의 PFEntityKey를 아는 것입니다. PFEntityToken이 있으면 PFEntityGetEntityKey를 사용하여 PFEntityKey를 검색할 수 있습니다.
PFEntityKey const* pEntityKey{};
std::vector<char> entityKeyBuffer;
size_t size{};
HRESULT hr = PFEntityGetEntityKeySize(entityHandle, &size); // Add your own error handling when FAILED(hr) == true
entityKeyBuffer.resize(size);
hr = PFEntityGetEntityKey(entityHandle, entityKeyBuffer.size(), entityKeyBuffer.data(), &pEntityKey, nullptr);
GetFile 호출
모든 PlayFab 호출은 요청 개체 준비, 호출 만들기(로그인에서 PFEntityHandle 사용), 응답을 받을 개체 만들기 및 GetResult 함수를 호출하여 새로 만든 컨테이너를 채우는 유사한 패턴을 따릅니다.
XAsyncBlock async{};
PFDataGetFilesRequest requestFiles{};
requestFiles.entity = pEntityKey;
HRESULT hr = PFDataGetFilesAsync(entityHandle, &requestFiles, &async); // Add your own error handling when FAILED(hr) == true
hr = XAsyncGetStatus(&async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage
size_t resultSize;
hr = PFDataGetFilesGetResultSize(&async, &resultSize);
std::vector<char> getFilesResultBuffer(resultSize);
PFDataGetFilesResponse* getFilesResponseResult{ nullptr };
hr = PFDataGetFilesGetResult(&async, getFilesResultBuffer.size(), getFilesResultBuffer.data(), &getFilesResponseResult, nullptr);
정리
게임을 종료할 준비가 되었거나 다른 이유로 PlayFab을 정리해야 하는 경우 열려 있는 모든 핸들을 닫고 PFServicesUninitializeAsync를 호출해야 합니다.
PFEntityCloseHandle(entityHandle);
entityHandle = nullptr;
PFServiceConfigCloseHandle(serviceConfigHandle);
serviceConfigHandle = nullptr;
XAsyncBlock async{};
HRESULT hr = PFServicesUninitializeAsync(&async); // Add your own error handling when FAILED(hr) == true
hr = XAsyncGetStatus(&async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage
비동기 API 패턴
GDK용 PlayFab 서비스 SDK는 GDK에 구현된 비동기 프로그래밍 모델을 따릅니다. 이 프로그래밍 모델에는 XAsync 라이브러리에서 제공하는 작업 및 작업 대기열의 사용이 포함됩니다. 이 모델은 다른 GDK 기능 및 확장(예: Xbox Services API)과 일치합니다. 약간의 복잡성이 발생하지만 비동기 작업에 대한 높은 수준의 제어도 제공합니다.
이 예는 PFDataGetFilesAsync에 대한 비동기 호출을 수행하는 방법을 보여줍니다.
auto async = std::make_unique<XAsyncBlock>();
async->callback = [](XAsyncBlock* async)
{
std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // take ownership of XAsyncBlock
size_t resultSize;
HRESULT hr = PFDataGetFilesGetResultSize(async, &resultSize);
if (SUCCEEDED(hr))
{
std::vector<char> getFilesResultBuffer(resultSize);
PFDataGetFilesResponse* getFilesResponseResult{ nullptr };
PFDataGetFilesGetResult(async, getFilesResultBuffer.size(), getFilesResultBuffer.data(), &getFilesResponseResult, nullptr);
}
};
PFDataGetFilesRequest requestFiles{};
requestFiles.entity = m_pEntityKey;
HRESULT hr = PFDataGetFilesAsync(m_entityHandle, &requestFiles, async.get());
if (SUCCEEDED(hr))
{
async.release(); // at this point, the callback will be called so release the unique ptr
}
오류 처리
완료된 XAsync 작업은 HTTP 상태 코드를 반환합니다. 오류 상태 코드는 XAsyncGetStatus() 또는 PF*Get() API 중 하나를 호출할 때 HTTP_E_STATUS_NOT_FOUND와 같은 실패 HRESULT로 나타납니다.
서비스에서 반환된 자세한 오류 메시지를 보려면 디버깅에 대한 다음 섹션을 참조하세요. 이러한 자세한 오류 메시지는 개발 중에 PlayFab 서비스가 클라이언트의 요청에 반응하는 방식을 더 잘 이해하는 데 유용할 수 있습니다.
디버깅
결과를 확인하고 PlayFab 서비스 SDK에서 모든 호출을 디버깅하는 가장 쉬운 방법은 디버그 추적을 활성화하는 것입니다. 디버그 추적을 활성화하면 디버거 출력 창에서 결과를 확인하고 결과를 게임 자체 로그에 연결할 수 있습니다.