本指南介绍了如何使用 Google Play 游戏服务提供的 Events API 收集玩家游戏数据以进行游戏分析。这些 API 可在 com.google.android.gms.games.event
和 com.google.android.gms.games
中找到。
准备工作
请阅读事件游戏概念(如果您尚未执行此操作)。
开始使用 Events API 进行编码之前,请执行以下操作:
- 在 Google Play 管理中心内为游戏定义事件。
- 遵循登录核对清单建议。
获取事件客户端
如需开始使用 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); } } }); }