Android 游戏中的事件

继 Google 登录 API 废弃之后，我们将在 2026 年移除游戏 v1 SDK。2025 年 2 月之后，您将无法在 Google Play 上发布新集成了游戏 v1 SDK 的游戏。我们建议您改用游戏 v2 SDK。
虽然已集成旧版游戏 v1 的现有游戏会继续运行几年，但建议您从 2025 年 6 月开始迁移到 v2。
本指南介绍如何使用 Play Games Services v1 SDK。有关最新 SDK 版本的信息，请参阅v2 文档。

本指南介绍如何使用 Google Play Games Services 提供的事件 API 收集玩家游戏数据用于游戏分析。这些 API 位于 com.google.android.gms.games.event 和 com.google.android.gms.games 中。

准备工作

如果您还没有，不妨参阅事件游戏概念，这可能会对您有所帮助。

开始使用事件 API 编码之前

获取事件客户端

要开始使用事件 API，您的游戏必须首先获取一个 EventsClient 对象。您可以通过调用 Games.getEventsClient() 方法并传入 activity 和当前玩家的 GoogleSignInAccount 来完成此操作。要了解如何检索玩家账号信息，请参阅Android 游戏中的登录。

提交事件

您可以在游戏中添加代码，以便在发生您游戏感兴趣的事件时通知 Google Play Games Services。

要发送事件更新，请调用 EventsClient.increment()，并传入 eventId 值和大于或等于 0 的整数 incrementAmount。

  • 当您首次在 Google Play 管理中心定义事件时，eventId 会由 Google Play Games Services 生成，用于在您的游戏中唯一标识此事件。
  • 您可以使用 incrementAmount 输入来指定玩家在完成某些特定游戏目标方面的量化进度。例如，如果您游戏要追踪的事件是“击败 500 只大眼睛怪物”，则 incrementAmount 值可以是玩家在一次战斗中击杀的怪物数量。

以下是使用增量为 1 提交事件的示例

public void submitEvent(String eventId) {
  Games.getEventsClient(this, GoogleSignIn.getLastSignedInAccount(this))
      .increment(eventId, 1);
}

检索事件

您可以通过调用 EventsClient.load() 检索存储在 Google 服务器上有关您游戏的所有事件数据。在方法调用中，传入一个布尔值以指示 Google Play Games Services 是否应清除用户设备上的本地缓存数据。

要检索您在 Google Play 管理中心定义的特定事件的数据，请调用 EventsClient.loadByIds() 并在输入参数中传入事件 ID 数组。

以下代码段显示了如何向 Google Play Games Services 查询您游戏的所有事件列表

public void loadEvents() {
  Games.getEventsClient(this, GoogleSignIn.getLastSignedInAccount(this))
      .load(true)
      .addOnCompleteListener(new OnCompleteListener<AnnotatedData<EventBuffer>>() {
        @Override
        public void onComplete(@NonNull Task<AnnotatedData<EventBuffer>> task) {
          if (task.isSuccessful()) {
            // Process all the events.
            for (Event event : task.getResult().get()) {
              Log.d(TAG, "loaded event " + event.getName());
            }
          } else {
            // Handle Error
            Exception exception = task.getException();
            int statusCode = CommonStatusCodes.DEVELOPER_ERROR;
            if (exception instanceof ApiException) {
              ApiException apiException = (ApiException) exception;
              statusCode = apiException.getStatusCode();
            }
            showError(statusCode);
          }
        }
      });
}