Android 遊戲事件

本指南說明如何使用 Google Play 遊戲服務提供的事件 API，收集玩家遊戲資料，以進行遊戲分析。您可以在 com.google.android.gms.games.event 和 com.google.android.gms.games 套件中取得此 API。

事前準備

建議您先複習事件遊戲概念，這會對您很有幫助。

開始使用事件 API 編寫程式碼之前：

取得事件用戶端

如要開始使用事件 API，遊戲必須先取得 EventsClient 物件。要取得此物件，您可以呼叫 PlayGames.getEventsClient() 方法，然後在活動內傳遞。

提交事件

您可以在遊戲中新增程式碼，以在遊戲發生特定事件時通知 Play 遊戲服務。

如要傳送事件更新，請使用 eventId 值以及等於或大於 0 的整數 incrementAmount 呼叫 EventsClient.increment()。

  • 首次在 Google Play 管理中心定義事件時，Play 遊戲服務會產生 eventId，用於在遊戲中識別此事件。

  • 您可以使用 incrementAmount 輸入指定玩家完成特定遊戲目標的量化進度。舉例來說，如果遊戲要追蹤的事件是「打敗 500 隻大眼怪」，incrementAmount 值可以是玩家在單次戰鬥中殺死的怪物數量。

以下是如何以遞增值為 1 提交事件的範例：

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

擷取事件

您可以呼叫 EventsClient.load() 以擷取 Google 伺服器儲存的所有遊戲事件資料。在方法呼叫中，傳入布林值以表示 Play 遊戲服務是否應清除使用者裝置中的本機快取資料。

如要擷取在 Google Play 管理中心定義的特定事件資料，請呼叫 EventsClient.loadByIds()，然後傳入輸入參數的事件 ID 陣列。

以下程式碼片段說明如何查詢 Play 遊戲服務，以取得遊戲的所有事件清單：

public void loadEvents() {
  PlayGames.getEventsClient(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);
          }
        }
      });
}