Android 遊戲中的事件

隨著 Google Sign-In API 淘汰，我們將在 2026 年移除遊戲第 1 版 SDK。2025 年 2 月後，您將無法在 Google Play 上發布新整合 games v1 SDK 的遊戲。建議您改用 games v2 SDK。
雖然採用舊版遊戲第 1 版整合功能的現有遊戲仍可繼續運作幾年，但建議您從 2025 年 6 月開始遷移至第 2 版。
本指南適用於使用 Play 遊戲服務第 1 版 SDK。如需最新 SDK 版本的相關資訊，請參閱 v2 說明文件。

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

事前準備

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

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

取得事件用戶端

如要開始使用事件 API，遊戲必須先取得 EventsClient 物件。方法是呼叫 Games.getEventsClient() 方法，然後傳入活動和目前播放器的 GoogleSignInAccount。如要瞭解如何擷取玩家帳戶資訊，請參閱「Android 遊戲登入」。

提交事件

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

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

  • 首次在 Google Play 管理中心定義事件時，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);
          }
        }
      });
}