遊戲統計資料

遊戲統計資料是遊戲的累積統計資料，玩家可以在玩家個人資料中查看。玩家可透過這些統計資料追蹤終身進度、查看精彩時刻，以及與其他玩家比較，還能使用 Google Play 的任務、社交挑戰等功能 (即將推出)。

遊戲統計資料必須符合以下規定：

• 不需購買 (例如購買寶石)，也就是說，他們不應因任何應用程式內購而更新。
• 不要求觀看廣告，也就是說，觀看廣告後不應更新。
• 不得為遊戲的通用用途 (例如開啟遊戲、使用設定)。
• 不得包含 Google Play 政策定義的個人和私密使用者資料，包括使用者 ID、密碼、精確位置或健康資料，或任何令人反感、褻瀆、露骨色情、暴力或仇恨內容。
• 適用於所有使用者 (例如，並非僅限團隊的動作，或僅適用於特定等級的使用者，或僅限於限時的 LiveOps 等)

整合步驟

使用遊戲統計資料 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 檔案中新增的統計資料顯示名稱字串，以利識別要新增本地化內容的統計資料。
    • 從語言代碼清單中指定語言。
    • 以指定語言新增顯示名稱的本地化版本。
    • 新增指定語言的統計資料說明本地化版本。

規劃結構定義

您可以使用 Game Stats API 傳送兩種資料：玩家事件和玩家進度統計資料的預先定義事件。

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

播放器事件

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

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

progressUpdate 個活動

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

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

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

設定統計資料

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

整合作業詳細資料

API 端點和 SDK 現已開放搶先體驗，並將於 2026 年 8 月正式發布。請參閱時間軸

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

何時應傳送資料

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

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++

里程碑