适用于 C++ 的 Play 游戏服务

在 Google 登录 API 弃用后，我们将在 2026 年移除 games v1 SDK。2025 年 2 月后，您将无法在 Google Play 上发布新集成了 games v1 SDK 的游戏。建议您改用 games v2 SDK。
虽然现有集成旧版 games 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 对象及其子 Managers 来调用 Play 游戏服务，包括：

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

4. 使用 GameServices 对象完毕后，将其重置或销毁。

更详细的层面：

1. 初始化平台配置：这是一个包含平台特定初始化信息的对象。在 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);
   

2. 构建 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);
   

3. 使用 Manager 类来管理您的 GameServices 对象。可以从 GameServices 实例访问 Manager，它们将相关功能分组在一起。例如 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();
   

4. 使用 GameServices 对象完毕后，通过在其所属的 unique_ptr 上调用 reset() 进行清理，或让 unique_ptr 在超出范围时自动将其销毁。

线程模型

除非另有说明，所有 GameServices 和 Manager 方法都具有线程安全的异步实现。它们可以在任何线程上调用，无需外部锁定，并且将按照其调用顺序一致地执行。

访问器方法（读取状态的方法）主要有两种变体。第一种方法（名称如 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 Games C++ SDK，请继续阅读快速入门指南。

延伸阅读

务必阅读 Google Play 游戏服务 C++ SDK 中附带的类文档，了解更多详情，并查看展示如何使用 SDK 的示例。

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