遊戲統計資料

「遊戲統計資料」是遊戲的累計統計資料，玩家可在玩家個人資料中查看，並追蹤遊戲歷程、查看精彩時刻，以及與其他玩家比較。這類資料未來也會支援 Google Play 功能，例如獎勵任務、社交挑戰等。

遊戲統計資料必須：

• 不要求購買 (例如購買寶石)，也就是說，不應因任何應用程式內購交易而更新。
• 不要求觀看廣告，也就是說，不應因觀看廣告而更新。
• 不應是遊戲的一般用途 (例如開啟遊戲、使用設定)。
• 不得包含 Play 政策定義的使用者個人和私密資料，包括使用者 ID、密碼、精確位置或健康資料，或任何令人反感、不雅、情色露骨、暴力或仇恨內容。
• 所有使用者都能參與 (例如，不是團隊專屬活動、僅限特定等級的使用者參與，或限時 LiveOps 等)

圖片：顯示「個人中心」分頁中玩家個人資料的遊戲統計資料。 「個人中心」分頁中的使用者介面 (UI) 僅供測試之用。遊戲統計資料使用者介面將於 2026 年 9 月推出。

匯總類型

匯總類型會指示 Google Play 如何根據您傳送的每個事件值計算統計資料：

• SUM：用於累計統計資料 (例如收集的金幣總數、造成的總傷害)。遊戲必須傳送每個事件例項中獲得的離散金額。
• COUNT：用於代表事件發生次數的統計資料 (例如遊戲次數、獲勝次數)。遊戲必須傳送離散事件發生例項。
• MAX：僅用於單次出現的最高成就 (例如單次執行的最高分數、最大連續組合或最高單場傷害)。請勿使用 MAX 做為解決方法，顯示預先計算的執行值中的生命週期總計。

重複統計資料的重要實作規定

• 傳送個別事件值：針對每個事件，只傳送該事件中發生的情況，例如單次遊戲中收集的金幣。然後在統計資料設定中設定匯總類型，例如 SUM 或 COUNT。這樣一來，重複的統計資料就能在參與機制中重複使用，Google Play 也能打造合適的玩家體驗。
• 請勿傳送生命週期總計：舉例來說，請勿追蹤玩家在遊戲用戶端或伺服器上收集的總金幣數，並使用 MAX 匯總傳送該總計。這類統計資料會繼續顯示在玩家個人資料使用者介面上，但 Google Play 無法用於提供聯盟、獎勵任務和衝刺等獎勵功能，提升玩家體驗並為遊戲帶來影響。

如需正確事件建模的操作說明和範例，請參閱「玩家事件」和「設定統計資料」。

整合步驟

使用 Game Stats API 傳送資料，做為重複統計資料的玩家活動，以及進度統計資料的預先定義事件 progressUpdate。您也需要設定邏輯，計算要顯示在玩家個人資料中的遊戲統計資料和顯示資訊。

玩家事件代表不同的遊戲內時刻、遊戲迴圈完成或進度里程碑。

播放器事件的定義和模型如下：

1. 事件代表玩家採取的特定動作，例如完成比賽、完成跑步、解鎖寶箱或儲存某個區域的進度。
2. 每項動作都會產生特定結果，或具有定義該動作的特定特徵。這些會模擬為事件屬性，提供事件及其特定結果的背景資訊 (例如比賽類型、該回合收集的金幣、比賽結果或爆頭次數)。

整合程序包含下列步驟：

• 宣告原始資料結構定義：在 Play 管理中心上傳 CSV 檔案，定義玩家事件。請參閱「建立事件」。
• 整合遊戲統計資料 API：以宣告格式傳送玩家活動和 progressUpdate 事件的原始玩家資料。
  • 使用用戶端或伺服器端整合，傳送所有定義的事件。 詳情請參閱播放器事件和 progressUpdate 事件的範例。
• 上傳 ZIP 檔案：提供 3 個 CSV 檔案和所有圖示圖片檔，定義 5 項重複統計資料和 1 個玩家進度等級。詳情請參閱 ZIP 檔案指南。 請提供下列詳細資料：
  • 重複統計資料的 CSV 檔案：
    • 統計資料的專屬 ID。
    • 指定用於計算統計資料的事件標籤。您無法在此使用 progressUpdate 事件標籤。
      • 指定要用於統計資料計算的屬性標籤。這必須是指定事件的屬性。
      • 指定匯總類型 (SUM、MAX、MIN 或 COUNT)，決定如何計算所選屬性標籤的統計資料。
      • 指定選用的篩選條件，只有在符合條件時才計算邏輯。定義屬性和事件標籤、運算子 (=、<、<=、>= 或 >) 和門檻值。
    • 加入布林值標記，指出統計資料是否可用於競賽功能。
    • 如果該功能可用於競爭功能，則為真實玩家的每小時最低和最高限制。我們會根據這項資訊，判斷玩家是否在參與聯賽和社群挑戰等功能時濫用系統。
    • 為玩家看到的統計資料提供不重複的顯示名稱。
    • 提供描述統計資料的獨特文字。這段說明應詳細說明玩家如何獲得這項統計資料，並在玩家個人資料 UI 中向玩家顯示。
    • 在 CSV 檔案中輸入確切的圖示檔案名稱，提供代表統計資料的專屬圖示。
    • 提供選用輸入內容，指出值增加或減少對玩家是否有利。這項輸入內容將用於慶祝球員動作。
    • 提供統計資料的選用測量單位，例如公里、英里和秒。
  • 玩家進度統計資料的 CSV 檔案：
    • 為玩家進度提供不重複的顯示名稱，讓玩家看到。
    • 請提供代表統計資料的專屬圖示。
    • 提供進度統計資料的說明。
    • 提供選用輸入內容，指出值增加或減少對玩家是否有利。只有在 currentProgress 屬性為 INT 類型時，系統才會使用這項輸入內容來慶祝玩家動作。
    • 提供統計資料的選用測量單位，例如公里、英里、秒。
  • 用於本地化的 CSV 檔案：為所有統計資料提供本地化顯示名稱。
    • 為每個本地化版本新增一列。
    • 使用先前 CSV 中新增的統計資料顯示名稱字串，不重複識別要新增本地化資訊的統計資料。
    • 從語言代碼清單中指定語言。
    • 為顯示名稱新增指定語言的本地化版本。
    • 為指定語言新增統計資料說明的本地化版本。

規劃結構定義

您可以使用遊戲統計資料 API 傳送兩種資料：玩家活動，以及玩家進度統計資料的預先定義事件。

以下範例說明玩家事件在各種遊戲類型中的樣貌：

播放器事件

玩家事件是由不同的遊戲內時刻、遊戲迴圈完成或進度里程碑定義。

• 定義事件：指定遊戲中的特定時刻、遊戲迴圈完成或進度里程碑：
  • 完成遊戲迴圈，例如完成一場比賽或一輪遊戲。
  • 進度里程碑，例如儲存區域探索進度或完成關卡。
  • 由於重複統計資料應確實代表玩家的可重複動作，因此定義的事件應與核心遊戲玩法相關聯。
• 新增屬性，提供事件及其結果的相關背景資訊，例如關卡編號、比賽類型、武器類型、武器數量、爆頭次數、收集的金幣、比賽結果、單圈時間或車輛類型。
• 在遊戲工作階段中，事件發生時立即傳送事件。舉例來說，在迴圈完成後立即傳送遊戲迴圈完成事件。

progressUpdate 個事件

如果遊戲有主要進度機制，請使用這個事件傳送玩家目前的進度。事件有一個預先定義的屬性，名為「currentProgress」，類型為 INT 或 STRING。您應使用這項屬性，傳送主要進度機制中玩家進度的目前值。如果使用這個事件，就必須提供預先定義的屬性「currentProgress」，並使用這個屬性定義進度統計資料。

您可以將遊戲中其他進度系統的目前值 (例如 lifetime highest score 或 current coin balance) 做為這個事件的其他屬性傳送。

玩家可以根據遊戲目前的進度比較個人資料，因此在首次整合後，必須立即取得目前的進度值。為了向玩家呈現準確的目前進度，您應在每個遊戲工作階段開始時，以及目前進度有更新時，傳送 progressUpdate 事件。

設定統計資料

您需要定義計算邏輯和每項統計資料的顯示資訊，藉此設定重複和進度統計資料。以下列舉不同遊戲類型的重複統計資料。重複統計資料通常是指在極少數 (3 到 4 個) 遊戲工作階段中，為任何玩家重複更新的統計資料，且與核心遊戲迴圈相關聯。

如要瞭解何時使用 SUM、COUNT 或 MAX，請參閱「選擇合適的匯總類型」。

整合作業詳細資料

本節說明如何建構事件，並在用戶端和伺服器端整合中傳送事件。

何時應傳送資料

玩家事件代表與遊戲迴圈完成或特定遊戲內時刻相關的遊戲內動作。請在事件發生後立即提交。舉例來說，遊戲迴圈完成後，請立即提交遊戲迴圈完成事件。

progressUpdate 事件代表玩家目前的進度等級。在下列情況下，應使用此事件傳送進度統計資料：

1. 只要目前進度有更新，就立即傳送最新值
2. 每當玩家啟動遊戲時，確保玩家隨時都有這項統計資料。

整合路徑

整合方式有兩種：用戶端和伺服器對伺服器。

伺服器對伺服器整合

公開 API 端點可讓您使用下列設定，在要求酬載中傳送事件：

HTTP 要求

POST https://games.googleapis.com/games/v1/players/{playerId}/gameStats: batchRecordEvents

路徑參數

授權和驗證

伺服器對伺服器 API 呼叫會遵循標準的伺服器端存取 Play 遊戲服務指南，使用 OAuth 2.0。要求必須包含以 https://www.googleapis.com/auth/games 範圍授權的不記名權杖。

事件：要求主體

後端 API 有嚴格的結構驗證限制：

• 批次大小：每個 BatchRecordEventsRequest 最多 30 個事件。
• 屬性數量：每個 PlayerGameEvent 最多可有 25 個自訂屬性。
• 長度限制：事件名稱 (最多 100 個字元)、屬性鍵 (最多 100 個字元) 和屬性字串值 (最多 1024 個字元)。
• 事件 ID：必須是有效的 36 個字元 UUID 字串。
• 重試和快取：如果 API 失敗，請避免在本機快取或累積過多事件，因為超過 30 個事件的批次重試會遭到拒絕。請一律將重試作業分塊，遵守批次大小限制。

BatchRecordEventsRequest

請參閱「BatchRecordEventsRequest」。

{
  "packageName": string,
  "requestTime": string,
  "events": [
    {
      object (PlayerGameEvent)
    }
  ]
}

PlayerGameEvent

{
  "eventId": string,
  "eventName": string,
  "eventProperties": {
    // keys (e.g., "matchId", "score")
    "": {
       object (PropertyValue)
    }
  },
  "eventTime": string // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z").
}

PropertyValue

// ONE of the following fields will be present:
{
// 64-bit integer formatted as a string to prevent data loss
"intValue": "string",
// Double-precision floating point number.
"doubleValue": number,
// Standard UTF-8 text string.
"stringValue": "string",
// Boolean value (true or false).
"boolValue": boolean,
// Duration in seconds suffixed with 's' (e.g., "240s" or "3.5s").
"durationValue": "string"
}

progressUpdate 事件：要求主體

BatchRecordEventsRequest

{
  "packageName": string,
  "requestTime": string,
  "events": [
    {
      object (PlayerGameEvent)
    }
  ]
}

PlayerGameEvent - progressUpdate

{
  "eventId": string,
  "eventName": "progressUpdate",
  "eventProperties": {
    "": {
       object (PropertyValue)
// Must have at least one property "currentProgress"  of  type  INT  or  STRING
    }
  },
  "eventTime": string // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z")
}

回應主體

如果成功，會傳回 HTTP 200 OK 狀態和空白 JSON 物件。

要求主體範例

事件：PlayerGameEvent

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-05-09T00:44:44Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID for deduplication and idempotency
      "eventName": "matchCompleted",
      "eventTime": "2026-05-09T01:44:44Z", // RFC 3339 formatted timestamp string (e.g., "2026-05-09T01:44:44Z").
      "eventProperties": {
        "matchId": {
          "stringValue": "Match_A"
        },
        "gameMode": {
          "stringValue": "Battle_B"
        },
        "locationId": {
          "stringValue": "Location_XYZ"
        },
        "playerElimination": {
          "intValue": 2
        },
        "isWinner": {
          "boolValue": true
        }
      }
    }
  ]
}

progressUpdate 事件

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-05-09T00:44:44Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID
      "eventName": "progressUpdate",
      "eventTime": "2026-05-09T01:44:44Z", // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z").
      "eventProperties": {
        "currentProgress": {
          "intValue": 52
        },
//Add more properties as per your requirement
      }
    }
  ]
}

用戶端實作

如要瞭解如何為平台實作遊戲統計資料用戶端，請參閱下列資源：

• Android
• Unity
• C++

里程碑