面向 C++ 的 Play 游戏服务

在弃用 Google 登录 API 后，我们将于 2026 年移除 games v1 SDK。2025 年 2 月之后，您将无法在 Google Play 上发布新集成了 games v1 SDK 的游戏。我们建议您改用 games 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::Builder 创建 GameServices 实例。

    在大多数实现中，只要您的 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. 使用 Manager 类来管理 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 和 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);});

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

平台特定信息

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

深入阅读

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

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