Skip to main content

빠른 시작: Android

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

요구 사항

프로젝트 설정

PlayFab SDK 릴리스 페이지에서 PlayFab Android SDK를 프로젝트에 다운로드하세요.

자체 프로젝트에 PlayFab C SDK 통합

다음 단계는 Android Studio를 사용하여 새 프로젝트를 만들었다고 가정하고 작성되었습니다.

게임에 바이너리 추가

프로젝트에 통합해야 하는 바이너리는 공유 객체 파일(.so)과 Android 아카이브 파일(.aar) 두 부분입니다. 바이너리를 직접 빌드하거나 릴리스 페이지에서 다운로드할 수 있습니다.

.so 파일 추가

이러한 파일은 CMake를 사용해 프로젝트에 통합됩니다.
  1. Android용 PlayFab SDK 릴리스의 압축을 풀고 원하는 디렉터리에 내용을 배치하세요.
  2. target_include_directories 또는 다른 동등한 함수를 사용하여 PlayFab SDK 릴리스의 “Include” 아래에 있는 헤더를 추가합니다:
  1. target_link_libraries 또는 다른 동등한 함수를 사용해 .so 파일의 위치를 프로젝트에 연결합니다. 예:

.aar 파일 추가

이러한 파일은 Gradle을 사용해 프로젝트에 통합됩니다.
  1. 앱 수준 Android 프로젝트 디렉터리 내에 libs 폴더를 생성합니다. 지금 프로젝트 디렉터리가 어떤 모습이어야 하는지에 대한 예:
  1. .aar 파일을 libs 폴더에 복사합니다.
  2. 앱 수준 build.gradle 파일(libs 폴더와 동일한 디렉터리에 있는 파일)의 dependencies 섹션에 다음 줄을 추가합니다. 두 번째 줄은 libHttpClient의 종속성으로 필요합니다.

초기화 및 로그인

이제 프로젝트가 Android용 PlayFab Services SDK를 사용하도록 완전히 설정되었으므로, 다음 단계에 따라 일부 샘플 호출을 작동시켜 보세요.

초기 설정

먼저 애플리케이션이 Android activity의 인스턴스를 갖도록 설정해야 합니다. 또한 NDK를 JNI(Java Native Interface)와 함께 사용하기 위해 작은 C/C++ 애플리케이션을 설정해야 합니다. 참고할 만한 작은 예제: https://github.com/android/ndk-samples/tree/android-mk/hello-jni. 이 예제에는 jstring을 반환하는 네이티브 메서드가 포함되어 있습니다:
네이티브 메서드를 사용하여 PFServices를 초기화하는 데 필요한 두 가지 요소인 Java VM과 애플리케이션 컨텍스트를 얻을 수 있습니다. 초기화 목적을 위해 유사한 메서드를 만들 수 있습니다:
그런 다음 JNIEnv 변수를 사용하여 Java VM을 검색할 수 있습니다.
다음으로, 애플리케이션 컨텍스트는 jobject 매개변수로 얻을 수 있습니다.
이제 이 두 변수를 저장했으므로 호출을 시작할 수 있습니다.

헤더

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

초기화

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

로그인

__PFServiceConfigHandle__을 얻은 후에는 이를 사용해 플레이어 로그인 호출을 수행할 수 있습니다. SDK에서는 __PFAuthenticationLoginWithCustomIDAsync__와 같은 PFAuthenticationLoginWith*Async 메서드를 사용합니다. 이 함수를 사용하면 사용자 지정 ID를 사용해 플레이어를 PlayFab에 로그인할 수 있습니다. 로그인 호출을 수행한 후 __XAsyncGetStatus__로 호출 상태를 확인할 수 있습니다. 상태는 __E_PENDING__으로 시작하여 호출이 성공적으로 완료된 후 __S_OK__로 변경됩니다. 어떤 이유로 호출이 실패하면 상태에 해당 실패가 반영됩니다. 모든 PlayFab Services 호출에 대한 오류 처리는 이 방식으로 작동합니다. S_OK 결과와 함께 __PFEntityHandle__을 다시 받게 됩니다. 이 핸들을 사용하여 로그인된 플레이어로서 이후의 PlayFab 호출을 수행합니다. 여기에는 해당 플레이어로 PlayFab 서비스에 인증하는 데 필요한 모든 자료가 포함됩니다.

서비스 호출

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

EntityKey 가져오기

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

GetFiles 호출

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

정리

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

비동기 API 패턴

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일