遊戲統計資料

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

整合步驟

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

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

玩家事件的定義和模型如下：

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

整合程序包含下列步驟：

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

活動的 CSV 檔案指南

您可以使用 PlayerGameEvent.csv 檔案匯入活動。

PlayerGameEvent.csv 格式

csv 檔案包含以半形逗號分隔的已宣告事件及其屬性，順序如下：

 Event Name,Property Name,Property Type

如果傳送 progressionStat 的 progressUpdate 事件，請為此事件新增一列。這個事件必須至少包含 INT 或 STRING 類型的 currentProgress 屬性，以及您想傳送的任何其他屬性。

統計資料的 ZIP 檔案指南

你可以透過 ZIP 檔案一次匯入統計資料。請參閱下表，瞭解適合在 ZIP 檔案中使用的確切檔案名稱：

RepetitiveStatsConfig.csv 格式

csv 檔案包含以半形逗號分隔的已宣告事件及其屬性，順序如下：

Stat ID, Event Name,    Property Name,  Aggregation,     Stat Display Name, Stat Description, Filter Property,  Filter Operator,    Filter Value,   Is Competitive, minLimit, maxLimit, Icon File Name, Sequence Number, Good value direction, unit

如果不想使用篩選條件，請將儲存格留空。

ProgressionStatConfig.csv 格式

csv 檔案包含以半形逗號分隔的已宣告事件及其屬性，順序如下：

Stat ID, Stat Display Name, Stat Description, Icon File Name, Good value direction, unit

玩家的玩家個人資料中會優先顯示進度統計資料。

StatLocalizations.csv 格式

csv 檔案包含以半形逗號分隔的已宣告事件及其屬性，順序如下：

Stat ID, Stat Display Name, Language Code, Localized Stat Name, Localized Stat Description

規劃結構定義

您可以使用 Game Stats API 傳送兩種資料：彈性玩家事件和玩家進度統計資料的預先定義事件。以下範例說明各種遊戲類型的彈性事件。

彈性播放器事件

玩家事件的定義包括遊戲中的特定時刻、遊戲循環完成次數或進度里程碑。

• 定義事件，例如遊戲中的特定時刻、遊戲迴圈完成次數或進度里程碑：
  • 完成遊戲迴圈，例如完成一場比賽或一次跑步。
  • 進度里程碑，例如已儲存的區域探索進度或完成的關卡。
• 新增屬性，提供事件和結果的相關資訊，例如關卡編號、比賽類型、武器類型、武器數量、爆頭次數、收集到的金幣數量、比賽結果、單圈時間或車輛類型。
• 在遊戲工作階段中，傳送事件時機應盡量及時。舉例來說，遊戲迴圈完成後，請立即傳送遊戲迴圈完成事件。

progressUpdate 個事件

如果遊戲有主要進度機制，請使用這個事件傳送玩家目前的進度。事件有一個預先定義的屬性，名為「currentProgress」，類型為 INT 或 STRING。請使用這個屬性傳送目前進度的值，因為這是玩家個人資料的遊戲統計資料使用者介面中唯一顯示的值。

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

整合作業詳細資料

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

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

何時應傳送資料

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

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

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

整合路徑

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

伺服器對伺服器整合

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

路徑參數

授權與驗證

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

彈性事件：要求主體

BatchRecordEventsRequest

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

PlayerGameEvent

{
  "eventId": string,
  "eventName": string,
  "eventProperties": {
    // keys (e.g., "matchId", "score")
    "": {
       object (PropertyValue)
    }
  },
  "eventTime": string
}

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,
// RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z").
"timestampValue": "string",
// 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
}

回應主體

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

要求主體範例

彈性事件：PlayerGameEvent

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-01-01T18:00:00Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID for deduplication //and idempotency
      "eventName": "matchCompleted",
      "eventTime": "2026-01-01T17:00:00Z",
      "eventProperties": {
        "matchId": {
          "stringValue": "Match_A"
        },
        "gameMode": {
          "stringValue": "Battle_B"
        },
        "locationId": {
          "stringValue": "Location_XYZ"
        },
        "playerElimination": {
          "intValue": 2
        },
        "survivalTimeSeconds": {
          "durationValue": "240s"
        },
        "isWinner": {
          "boolValue": true
        }
      }
    }
  ]
}

progressUpdate 事件

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-01-01T18:00:00Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID
      "eventName": "progressUpdate",
      "eventTime": "2026-01-01T17:00:00Z",
      "eventProperties": {
        "currentProgress": {
          "intValue": 52
        },
//Add more properties as per your requirement
      }
    }
  ]
}

用戶端整合

我們將透過 Unity、Java 和 C++ SDK 提供用戶端整合功能。

整合用戶端 PlayerGameEvent 時，您需要視 SDK 而定，在觸發點以 Java 或 Csharp 建構事件物件，並使用 SDK 提供的上傳函式傳送這些物件。

同樣地，對於 progressUpdate 事件，請使用 currentProgress 屬性記錄更新的進度，並使用 SDK 提供的上傳函式傳送這些屬性。

事件

「PlayerGameEvent」的用戶端整合方式如下：

建構彈性播放器遊戲事件

// Build the PlayerGameEvent
PlayerGameEvent event = new PlayerGameEvent.Builder("matchCompleted")
  .addProperty("matchId", "Match_A")
  .addProperty("gameMode", "Battle_B")
  .addProperty("mapId", "Location_XYZ")
  .addProperty("isWinner", true)
  .addProperty("survivalTimeSeconds", "240s")
  .addProperty("playerElimination", 2)
  .build();

List events = new ArrayList<>();
// ... populate list ...

// Build the PlayerGameEvent
var playerEvent = new PlayerGameEvent.Builder("matchCompleted")
   .AddProperty("matchId", "Match_A")
   .AddProperty("gameMode", "Battle_B")
   .AddProperty("mapId", "Location_XYZ")
   .AddProperty("isWinner", true)
   .AddProperty("survivalTimeSeconds", "240s")
   .AddProperty("playerElimination", 2)
   .Build();
var events = new List();
// ... populate list ...

// Build the PlayerGameEvent
PgsPlayerGameEvent* player_event = PgsPlayerGameEvent_create("matchCompleted");
if (player_event != nullptr) {
   PgsPlayerGameEvent_putString(player_event, "matchId", "Match_A");
   PgsPlayerGameEvent_putString(player_event, "gameMode", "Battle_B");
   PgsPlayerGameEvent_putString(player_event, "mapId", "Location_XYZ");
   PgsPlayerGameEvent_putBoolean(player_event, "isWinner", true);
   PgsPlayerGameEvent_putString(player_event, "survivalTimeSeconds", "240s");
   PgsPlayerGameEvent_putLong(player_event, "playerElimination", 2);
}

建構 progressUpdate Player Game Event

// Build the PlayerGameEvent
PlayerGameEvent event = new PlayerGameEvent.Builder("progressUpdate")
  .addProperty("currentProgress", 52)
  // Add other properties if needed
  .build();

List events = new ArrayList<>();
// ... populate list ...

// Build the PlayerGameEvent
var progressEvent = new PlayerGameEvent.Builder("progressUpdate")
   .AddProperty("currentProgress", 52)
   // Add other properties if needed
   .Build();
var events = new List();
// ... populate list ...

PgsPlayerGameEvent* progress_event = PgsPlayerGameEvent_create("progressUpdate");
if (progress_event != nullptr) {
   PgsPlayerGameEvent_putLong(progress_event, "currentProgress", 52);
}

記錄事件並上傳

// Buffers the event locally.
client.recordEvent(event);

// Buffers the events locally, (List version)
client.recordEvents(events);

// This submits the events to PGS
client.requestEventsUpload();

// Buffers the event locally.
PlayGamesPlatform.Instance.RecordEvent(playerEvent);

// Buffers the events locally, (List version)
PlayGamesPlatform.Instance.RecordEvents(events);

// This submits the events to PGS
PlayGamesPlatform.Instance.RequestEventsUpload();

// Record the event
PgsGameStatsClient_recordEvent(client, player_event);

// This submits the events to PGS
PgsGameStatsClient_requestEventsUpload(client);

// Clean up handle to avoid leaks
PgsPlayerGameEvent_destroy(player_event);

// Clean up client handle when PGS operations are finished
PgsGameStatsClient_destroy(client);

時間軸