Android 游戏中的事件

本指南介绍了如何使用 Events API 收集玩家游戏数据以进行游戏分析 由 Google Play 游戏服务提供这些 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 值和 等于或大于 0 的整数 incrementAmount。

  • eventId 由 Google Play 游戏服务在您首次定义 事件，用于在 Google Play 管理中心内 您的游戏。
  • 您可以使用 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);
          }
        }
      });
}