Android 遊戲中的事件

本指南說明如何使用 Google Play 遊戲服務提供的事件 API 收集玩家遊戲資料,以便進行遊戲分析。此 API 位於 com.google.android.gms.games.eventcom.google.android.gms.games

事前準備

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

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

取得事件用戶端

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

提交活動

您可以在遊戲中新增程式碼,讓系統在發生遊戲感興趣的事件時,通知 Google Play 遊戲服務。

如要傳送活動更新,請呼叫 EventsClient.increment(),其 eventId 值以及等於或大於 0 的整數 incrementAmount

  • 當您在 Google Play 管理中心首次定義事件時,Google Play 遊戲服務就會產生 eventId,用來在遊戲中明確識別該事件。
  • 您可以使用 incrementAmount 輸入指定玩家完成特定遊戲目標的量化進度。舉例來說,如果遊戲要追蹤的事件是「打敗 500 隻大眼怪」incrementAmount 值可以是玩家在單次戰鬥中殺死的怪物數量。

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

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

擷取事件

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

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

下列程式碼片段說明如何查詢 Google 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);
          }
        }
      });
}