面向 C++ 的 Play 游戏服务

随着 Google Sign-In API 的废弃，我们将于 2026 年移除游戏 v1 SDK。自 2025 年 2 月起，您将无法在 Google Play 上发布新集成了游戏 v1 SDK 的游戏。我们建议您改用游戏 v2 SDK。
虽然集成旧版游戏 v1 的现有游戏在未来几年内仍可正常运行，但我们建议您从 2025 年 6 月开始迁移到 v2。
本指南适用于 Play 游戏服务 v1 SDK。适用于 Play 游戏服务 v2 的 C++ SDK 尚未推出。

Google Play 游戏服务 C++ SDK 提供了可与 Google Play 游戏服务配合使用的 C++ API，专为已有 C++ 游戏实现的开发者而设计。

该 SDK 目前实现了以下服务：

• 授权
• 成就
• 排行榜
• 事件
• 游戏存档
• 附近连接（仅限 Android）
• 玩家统计信息

概念

大体上讲，您需要执行以下步骤来使用 SDK：

1. 为 Android 设置平台配置。
2. 使用 GameServices::Builder 配置并构建 GameServices 对象。GameServices 对象会自动尝试登录，并通过 OnAuthActionFinished() 回调返回结果。记下回调所返回的结果。如果自动登录尝试失败，您可以显示一个按钮供用户手动登录。

3. 收到 OnAuthActionFinished() 结果后，您可以使用 GameServices 对象及其子对象管理器来进行 Play 游戏服务调用，包括：

   • 登录（授权失败后）：StartAuthorizationUI()
   • 解锁成就：Achievements().Unlock()
   • 使用内置界面显示成就：Achievements().ShowAllUI()
   • 提交最高得分：Leaderboards().SubmitScore()
   • 退出账号：SignOut()

4. 当您使用完 GameServices 对象时，请将其重置或销毁。

详细来说，您需要执行以下步骤：

1. 初始化平台配置：这是一个包含平台特定初始化信息的对象。在 Android 上，平台配置包含 Java 虚拟机和指向当前 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);
   

2. 构建一个 GameServices 对象：该对象是 Google Play 游戏服务功能的主要入口点。GameServices 实例通过 GameServices::Builder 创建。

   在大多数实现中，只要您的 C 环境持续存在，给定 GameServices 对象就会持续存在；在 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);
   

3. 使用管理器类来管理 GameServices 对象。管理器可通过 GameServices 实例访问，用于将相关功能分组管理，例如成就管理器和排行榜管理器。它们本身不含用户可见状态。管理器以引用形式返回，其生命周期由所属的 GameServices 实例控制。您的客户端绝不应持有管理器引用，而应持有 GameServices 实例。

   管理器通过不可变值类型的对象返回数据。这些值反映了查询执行时底层数据的一致状态。

   // Submit a high score
   game_services_->Leaderboards().SubmitScore(leaderboard_id, score);
   
   // Show the default Achievements UI
   game_services_->Achievements().ShowAllUI();
   

4. 当您不再使用 GameServices 对象时，可通过调用其所属 unique_ptr 的 reset() 进行清理，或让 unique_ptr 在超出作用域时自动销毁该对象。

线程模型

除非另有说明，否则所有 GameServices 和管理器方法都拥有线程安全异步实现。它们可在任何线程上调用，无需外部锁定，并且执行顺序与其调用顺序一致。

访问器方法（读取状态的方法）具有两种主要变体。第一种方法（名称格式如 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);});

所有用户回调均在一个专用回调线程上调用。该线程可能不同于“主线程”或“界面线程”的任何平台概念。您还应尽力确保用户回调能快速执行；如果回调线程停滞，可能会导致用户可见的问题（例如，退出账号请求延迟完成）。

平台特定信息

要开始在 Android 上使用 Play 游戏 C++ SDK，请继续阅读快速入门指南。

深入阅读

务必阅读 Google Play 游戏服务 C++ SDK 自带的类文档以了解更多详情，并查看演示 SDK 使用方法的示例。

如果您的游戏使用后端服务器，请参阅启用 Google Play 游戏服务的服务器端访问。