C++용 Play 게임즈 서비스
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
Google 로그인 API가 지원 중단됨에 따라 2026년에 게임 v1 SDK가 삭제됩니다. 2025년 2월 이후에는 게임 v1 SDK와 새로 통합된 타이틀을 Google Play에 게시할 수 없습니다. 대신 games v2 SDK를 사용하는 것이 좋습니다.
이전 게임 v1 통합이 적용된 기존 타이틀은 몇 년 동안 계속 작동하지만 2025년 6월부터는 v2로 이전하는 것이 좋습니다.
이 가이드는 Play 게임즈 서비스 v1 SDK 사용에 관한 가이드입니다. Play 게임즈 서비스 v2용 C++ SDK는 아직 사용할 수 없습니다.
Google Play 게임 서비스 C++ SDK는 Google Play 게임 서비스와 함께 사용할 수 있는 C++ API를 제공합니다. 이는 C++로 구현된 기존 게임을 보유한 개발자를 위한 것입니다.
현재 SDK로 다음 서비스를 구현할 수 있습니다.
- 인증
- 업적
- 리더보드
- 이벤트
- 저장된 게임
- Nearby Connections(Android에만 해당)
- 플레이어 통계
개념
고급 단계에서 다음 절차에 따라 SDK를 사용합니다.
- Android의 플랫폼 구성을 설정합니다.
GameServices::Builder를 사용하여 GameServices 객체를 구성하고 생성합니다. GameServices 객체가 자동으로 로그인을 시도하고 OnAuthActionFinished() 콜백을 통해 결과를 반환합니다. 이때 콜백이 반환한 결과를 기록해 둡니다. 자동 로그인 시도가 실패한 경우 사용자가 로그인하도록 버튼을 표시할 수 있습니다.OnAuthActionFinished() 결과를 수신한 후, GameServices 객체와 하위 Manager를 사용하여 다음을 포함한 Play 게임즈 서비스를 호출할 수 있습니다.
- 로그인 (인증 실패 후):
StartAuthorizationUI()
- 업적 달성:
Achievements().Unlock()
- 기본 제공 UI를 사용하여 업적 표시:
Achievements().ShowAllUI()
- 최고점수 제출:
Leaderboards().SubmitScore()
- 로그아웃:
SignOut()
GameServices 객체 사용을 마치면 재설정하거나 삭제합니다.
보다 구체적인 절차는 다음과 같습니다.
플랫폼 설정 초기화: 플랫폼별 초기화 정보가 포함된 객체입니다. Android의 경우 플랫폼 설정에 Java VM과 현재 Activity로 연결되는 포인터가 포함됩니다.
// In android_main(), create a platform configuration
// and bind the object activity.
// Alternately, attach the activity in JNI_Onload().
gpg::AndroidPlatformConfiguration platform_configuration;
platform_configuration.SetActivity(state->activity->clazz);
GameServices 객체 구성: 이 객체는 Google Play 게임 서비스 기능의 주요 진입점입니다. GameServices 인스턴스는 GameServices::Builder로 생성됩니다.
대부분의 구현에서 주어진 GameServices 객체는 C 환경이 존재하는 한 계속 존재합니다. 따라서Android Activity가 일시중지되고 재개될 때도 다시 초기화할 필요가 없습니다.
// Creates a GameServices object that has lambda callbacks.
game_services_ = gpg::GameServices::Builder()
.SetDefaultOnLog(gpg::LogLevel::VERBOSE)
.SetOnAuthActionStarted([started_callback](gpg::AuthOperation op) {
is_auth_in_progress_ = true;
started_callback(op);
})
.SetOnAuthActionFinished([finished_callback](gpg::AuthOperation op,
gpg::AuthStatus status) {
LOGI("Sign in finished with a result of %d", status);
is_auth_in_progress_ = false;
finished_callback(op, status);
})
.Create(pc);
Manager 클래스를 사용하여 GameServices 객체를 관리합니다. Manager는 GameServices 인스턴스에서 액세스하고 관련 기능을 함께 그룹화합니다. 이러한 예에는 Achievement와 Leaderboard Manager가 포함됩니다. 여기에는 사용자가 볼 수 있는 상태가 없습니다. Manager는 참조로 반환되고 포함된 GameServices 인스턴스가 수명 주기를 제어합니다. 클라이언트가 Manager 참조를 보유해서는 안 됩니다. 대신 클라이언트는 GameServices 인스턴스를 보유해야 합니다.
Manager는 변경할 수 없는 값 유형 개체를 통해 데이터를 반환합니다. 이러한 값은 쿼리가 실행된 시점에서 기본 데이터의 일관된 뷰를 반영합니다.
// Submit a high score
game_services_->Leaderboards().SubmitScore(leaderboard_id, score);
// Show the default Achievements UI
game_services_->Achievements().ShowAllUI();
GameServices 객체 사용을 마치면 객체를 소유하고 있는 unique_ptr에서 reset()을 호출하거나 범위를 벗어날 때 unique_ptr이 자동으로 객체를 제거하도록 하여 정리합니다.
스레딩 모델
별도의 언급이 없는 경우 모든 GameServices 및 Manager 메서드는 스레드로부터 안전한 비동기 구현을 이용합니다. 외부 잠금 없이 모든 스레드에서 호출될 수 있으며 호출 순서와 일치하는 순서대로 실행됩니다.
Accessor 메서드(상태를 읽는 메서드)에는 두 개의 주요 변형이 있습니다. FetchProperty()와 같은 이름을 가진 첫 번째 메서드 유형은 제공된 콜백에 비동기적으로 결과를 제공합니다. FetchPropertyBlocking()와 같은 이름을 가진 두 번째 유형은 호출 스레드에 동기적으로 결과를 반환합니다.
// Blocking callback
gpg::AchievementManager::FetchAllResponse fetchResponse =
game_services_->Achievements().FetchAllBlocking(std::chrono::milliseconds(1000));
// Non-blocking callback
game_services_->Achievements().FetchAll(gpg::DataSource::CACHE_OR_NETWORK,
[] (gpg::AchievementManager::FetchAllResponse response) {
LogI("Achievement response status: %d", response.status);});
모든 사용자 콜백은 전용 콜백 스레드에서 호출됩니다. 이 스레드는 '기본 스레드' 또는 'UI 스레드'의 플랫폼 개념과 다를 수 있습니다. 아울러 사용자 콜백이 빨리 실행되도록 해야 합니다. 콜백 스레드가 지연되면 로그아웃 요청 완료 지연같이 사용자에게 보이는 문제가 발생할 수 있습니다.
Android에서 Play 게임 C++ SDK를 시작하려면 빠른 시작 가이드로 계속 진행하세요.
추가 자료
Google Play 게임 서비스 C++ SDK에 포함된 클래스 설명서에서 자세한 내용을 알아보고, SDK 사용 방법을 시연하는 샘플도 확인해 보세요.
게임에서 백엔드 서버를 사용하는 경우 Google Play 게임즈 서비스에 서버 측 액세스 사용 설정을 참고하세요.
이 페이지에 나와 있는 콘텐츠와 코드 샘플에는 콘텐츠 라이선스에서 설명하는 라이선스가 적용됩니다. 자바 및 OpenJDK는 Oracle 및 Oracle 계열사의 상표 또는 등록 상표입니다.
최종 업데이트: 2025-07-26(UTC)
[null,null,["최종 업데이트: 2025-07-26(UTC)"],[],[],null,["# Play Games Services for C++\n\nFollowing the deprecation of the\n[Google Sign-In](https://android-developers.googleblog.com/2024/09/streamlining-android-authentication-credential-manager-replaces-legacy-apis.html)\nAPI, we are removing the games v1 SDK in 2026. After February 2025, you will be unable to publish\ntitles that are newly integrated with games v1 SDK, on Google Play. We recommend that you use the\ngames v2 SDK instead. \n\nWhile existing titles with the previous games v1 integrations continue to function for a\ncouple of years, you are encouraged to\n[migrate to v2](/games/pgs/android/migrate-to-v2)\nstarting June 2025. \n\nThis guide is for using the Play Games Services v1 SDK. The C++ SDK for\nPlay Games Services v2 is not yet available.\n\nThe Google Play games Services C++ SDK provides a C++ API for use with Google Play Game\nservices, and is meant for developers who have an existing C++ implementation\nof their game.\n\nCurrently, the SDK implements the following services:\n\n- Authorization\n- Achievements\n- Leaderboards\n- Events\n- Saved Games\n- Nearby Connections (Android only)\n- Player Statistics\n\nConcepts\n--------\n\nAt a high level, you use the SDK by following these steps:\n\n1. Set up a platform configuration for Android.\n2. Use a `GameServices::Builder` to configure and construct a `GameServices` object. The `GameServices` object automatically attempts to sign in, and returns the result via an `OnAuthActionFinished()` callback. Take note of the result returned by the callback. If the automatic sign-in attempt failed, you can display a button to let users sign in.\n3. After receiving the `OnAuthActionFinished()` result, you can use the\n `GameServices` object and its child Managers to make Play Games services calls,\n including:\n\n - Sign in (after authorization fails): `StartAuthorizationUI()`\n - Unlock achievements: `Achievements().Unlock()`\n - Show achievements using built-in UI: `Achievements().ShowAllUI()`\n - Submit a high score: `Leaderboards().SubmitScore()`\n - Sign out: `SignOut()`\n4. When you are done using the `GameServices` object, reset or destroy it.\n\nAt a more detailed level:\n\n1. Initialize a platform configuration: This is an object that contains\n platform-specific initialization information. On Android, the platform configuration contains the\n Java VM and a pointer to the current `Activity`:\n\n // In android_main(), create a platform configuration\n // and bind the object activity.\n // Alternately, attach the activity in JNI_Onload().\n gpg::AndroidPlatformConfiguration platform_configuration;\n platform_configuration.SetActivity(state-\u003eactivity-\u003eclazz);\n\n2. Construct a `GameServices` object: This object is the main entry point for\n Google Play games Services functionality. `GameServices` instances are created\n with `GameServices::Builder`.\n\n In most implementations, a given `GameServices` object will persist as long as\n your C environment does; you do not need to reinitialize it when your\n Android `Activity` pauses and resumes. \n\n // Creates a GameServices object that has lambda callbacks.\n game_services_ = gpg::GameServices::Builder()\n .SetDefaultOnLog(gpg::LogLevel::VERBOSE)\n .SetOnAuthActionStarted([started_callback](gpg::AuthOperation op) {\n is_auth_in_progress_ = true;\n started_callback(op);\n })\n .SetOnAuthActionFinished([finished_callback](gpg::AuthOperation op,\n gpg::AuthStatus status) {\n LOGI(\"Sign in finished with a result of %d\", status);\n is_auth_in_progress_ = false;\n finished_callback(op, status);\n })\n .Create(pc);\n\n3. Use the Manager classes to manage your `GameServices` object. Managers are accessed from a `GameServices` instance and group related functionality\n together. Examples of these\n include the Achievement and Leaderboard Managers. They contain no user-visible\n state themselves. Managers are returned by reference, and the containing\n `GameServices` instance controls their lifecycle. Your client should never hold\n onto a Manager reference. Instead, your client should hold on to the\n `GameServices` instance.\n\n Managers return data via immutable value type objects. These values\n reflect a consistent view of the underlying data at the point in time when\n the query was made. \n\n // Submit a high score\n game_services_-\u003eLeaderboards().SubmitScore(leaderboard_id, score);\n\n // Show the default Achievements UI\n game_services_-\u003eAchievements().ShowAllUI();\n\n4. When you are finished using the `GameServices` object, clean up by\n calling `reset()` on the `unique_ptr` that owns it, or by letting the\n `unique_ptr` automatically destroy it when going out of scope.\n\nThreading model\n---------------\n\nUnless otherwise noted, all `GameServices` and Manager methods have\nthread-safe, asynchronous implementations. They can be called on any thread without\nexternal locking, and will execute in an order consistent with their invocation\norder.\n\nAccessor methods (those that read state) come in two major variants. The first\ntype of method (with names like `FetchProperty()`) asynchronously supplies its results\nto a provided callback; the second (with names like\n`FetchPropertyBlocking()`) synchronously returns its results to the calling\nthread. \n\n // Blocking callback\n gpg::AchievementManager::FetchAllResponse fetchResponse =\n game_services_-\u003eAchievements().FetchAllBlocking(std::chrono::milliseconds(1000));\n\n // Non-blocking callback\n game_services_-\u003eAchievements().FetchAll(gpg::DataSource::CACHE_OR_NETWORK,\n [] (gpg::AchievementManager::FetchAllResponse response) {\n LogI(\"Achievement response status: %d\", response.status);});\n\nAll user callbacks are invoked on a dedicated callback thread. This thread is\npotentially distinct from any platform concept of a \"main thread\" or \"UI\nthread\". You should also try to ensure that user callbacks execute quickly; a stalled callback thread\nmay cause user-visible issues (for example, delayed completion of a sign-out\nrequest).\n\nPlatform-specific information\n-----------------------------\n\nTo get started using the Play Games C++ SDK on Android, continue to the\n[quickstart guide](/games/pgs/v1/cpp/quickstart).\n\nFurther reading\n---------------\n\nBe sure to read the class documentation that comes in the Google Play Game\nservices C++ SDK for further details, and check out the\n[samples](https://github.com/playgameservices/) that demonstrate how to use the SDK.\n\nIf your game uses a backend server, see\n[Enabling Server-Side Access to Google Play Games Services](/games/pgs/v1/android/server-access)."]]
