Android 游戏中的事件

在弃用 Google 登录 API 后，我们将于 2026 年移除 games v1 SDK。2025 年 2 月之后，您将无法在 Google Play 上发布新集成了 games v1 SDK 的游戏。我们建议您改用 games v2 SDK。
虽然采用旧版游戏 v1 集成的现有游戏仍可在未来几年内正常运行，但我们建议您从 2025 年 6 月开始迁移到 v2。
本指南介绍了如何使用 Play 游戏服务 v1 SDK。如需了解最新的 SDK 版本，请参阅 v2 文档。

本指南介绍了如何使用 Google Play 游戏服务提供的 Events API 收集玩家游戏数据以进行游戏分析。这些 API 可在 com.google.android.gms.games.event 和 com.google.android.gms.games 中找到。

准备工作

请阅读事件游戏概念（如果您尚未执行此操作）。

开始使用 Events API 进行编码之前，请执行以下操作：

获取事件客户端

如需开始使用 Events API，您的游戏必须先获取一个 EventsClient 对象。为此，您可以调用 Games.getEventsClient() 方法，并传入 activity 和当前播放器的 GoogleSignInAccount。如需了解如何检索玩家的账号信息，请参阅 Android 游戏中的登录功能。

提交事件

您可以在游戏中添加代码，以便在发生与您游戏相关的事件时发送通知给 Google Play 游戏服务。

如需发送事件更新，请调用 EventsClient.increment()，并包含 eventId 值和 incrementAmount（等于或大于 0 的整数）。

  • 您首次在 Google Play 管理中心内定义事件时会生成 eventId，它用于在您的游戏中唯一标识此事件。
  • 您可以使用 incrementAmount 输入指定玩家完成某个游戏专属目标的量化进度。例如，如果您的游戏想要跟踪的事件是“打败 500 只凸眼怪”，则 incrementAmount 值可以是玩家在单场战斗中杀死的怪物数量。

下例展示了如何提交增量为 1 的事件：

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

检索事件

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

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

以下代码段展示了如何在 Google Play 游戏服务中查询您的游戏的所有事件列表：

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);
          }
        }
      });
}