游戏统计数据

游戏统计数据是有关游戏的累积统计数据，玩家可以在自己的玩家资料中查看这些数据。借助这些统计数据，玩家可以跟踪自己的生涯进度、查看精彩瞬间并与其他玩家进行比较，还可以在未来使用 Google Play 的任务、社交挑战等功能。

集成步骤

使用 Game Stats API 发送数据，将重复性统计信息作为灵活的玩家事件，将进度统计信息作为预定义的事件 progressUpdate。您还需要配置用于计算玩家个人资料中显示的统计信息的逻辑及其显示信息。

玩家事件表示不同的游戏内时刻、游戏循环完成情况或进度里程碑。

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

  1. 事件是指玩家采取的特定行动，例如完成比赛、完成跑步、解锁宝箱或保存某个区域的进度。
  2. 每项操作都会产生特定的结果或具有定义该操作的特定特征。这些数据会以事件属性的形式呈现，提供有关事件及其具体结果的背景信息（例如，比赛类型、相应跑动期间收集的币数、比赛结果或爆头次数）。

集成包括以下步骤：

  • 声明原始数据架构：在 Play 管理中心内使用 CSV 上传定义玩家事件。请参阅 CSV 文件指南。
  • 与 Game Stats API 集成：以声明的格式发送原始玩家数据，以实现灵活的玩家事件和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 必需

PlayerGameEvent.csv 格式

该 CSV 文件包含声明的事件及其属性，这些内容以逗号分隔值形式按以下顺序排列：

 Event Name,Property Name,Property Type

如果您为 progressionStat 发送 progressUpdate 事件，请为此事件添加一行。此事件必须包含至少一个 INT 或 STRING 类型的 currentProgress 属性，以及您要发送的任何其他属性。

示例表格
事件名称 属性名称 属性类型
matchCompleted 时长 DOUBLE
matchCompleted 击杀 INT
matchCompleted isWinner BOOLEAN
matchCompleted matchType STRING (UTF-8)
itemCollected coinsAmount INT
itemCollected weaponType STRING (UTF-8)
progressUpdate currentProgress INT

统计数据的 ZIP 文件指南

您可以使用 ZIP 文件一次性导入统计数据。请参阅下表，了解要在 ZIP 文件中使用的确切文件名：

文件名 是必需还是可选 接受的值
RepetitiveStatsConfig.csv 必需 许多事件的元数据。
ProgressionStatConfig.csv 必需 已声明的事件及其属性。
StatLocalizations.csv 可选 提供成就名称和说明的翻译。
图标文件 必需 采用 512 x 512 PNG、JPEG 或 JPG 格式的图标。

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

如果您不想使用过滤条件，请将相应单元格留空。

示例表格
统计信息 ID 事件名称 属性名称 聚合 统计数据显示名称 统计数据说明 过滤媒体资源（可选） 过滤条件运算符（可选） 过滤条件值（可选） 具有竞争力 minLimit maxLimit Icon filename 序列号 “性价比高”方向 单位
1 matchCompleted 时长 MAX 最长匹配生存时间 表示玩家在任何比赛中的存活时间 isWinner = TRUE TRUE 0 50 stat1.png 1 递减 秒
2 matchCompleted isWinner COUNT 获胜场次 表示玩家赢得的比赛次数 isWinner = TRUE TRUE 0 50 stat3.png 2 增加
3 matchCompleted 击杀 SUM 1 对 1 对战击杀数 在 1 对 1 比赛中获得的击杀数 matchType = “1 对 1” FALSE stat4.png 4 增加
4 itemCollected coinsAmount SUM 收集到的黄金总数 玩家在比赛中收集金币 weaponType = "sword" FALSE stat2.png 3 增加

ProgressionStatConfig.csv 格式

该 CSV 文件包含声明的事件及其属性，这些内容以逗号分隔值形式按以下顺序排列：

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

进度统计数据将作为玩家资料中的第一个统计数据向玩家显示。

示例表格
统计 ID 统计数据的显示名称 统计数据说明 图标文件名 良好的价值方向
5 级别 玩家可以通过参加对局来累积经验值并升级。 Level.png 增加

StatLocalizations.csv 格式

该 CSV 文件包含声明的事件及其属性，这些内容以逗号分隔值形式按以下顺序排列：

Stat ID, Stat Display Name, Language Code, Localized Stat Name, Localized Stat Description
示例表格
统计 ID 统计数据的显示名称 语言代码 本地化统计名称 (UTF-8) 本地化统计数据说明 (UTF-8) 1 最长匹配生存 es 在对局中存活更长时间 Esto denota el tiempo de supervivencia de una jugadora en cualquier partido. 1 最长匹配生存 fr 最长比赛的生存时间 Cela indique la durée de survie d'un joueur dans n'importe quel match. 4 收集到的黄金总数 es 收集到的总金币数 La jugadora recoge monedas mientras juega en un partido 4 收集到的黄金总数 fr 或 total collecté Le joueur collecte des pièces en jouant un match

规划架构

您可以使用 Game Stats API 发送两种类型的数据：灵活的玩家事件和用于玩家进度统计信息的预定义事件。以下示例展示了各种游戏类型的灵活事件。

灵活的播放器事件

玩家事件由不同的游戏内时刻、游戏循环完成情况或进度里程碑定义。

  • 将事件定义为特定的游戏内时刻、游戏循环完成情况或进度里程碑：
    • 游戏循环完成情况，例如完成的比赛或跑步。
    • 进度里程碑，例如已保存区域的探索进度或已完成的关卡。
  • 添加属性，以提供有关事件及其结果的背景信息，例如关卡编号、比赛类型、武器类型、武器数量、爆头次数、收集的币数、比赛结果、圈速或汽车类型。
  • 在游戏会话中，发送事件的时间应尽可能早。例如，在游戏循环完成后立即发送游戏循环完成事件。
示例
游戏类型 事件标签 游戏内时刻 / 进度事件完成 / 游戏循环完成 结果 特性
线性推进式独立益智游戏 chapter_completed 完成进度事件 不适用 章节编号、章节名称、尝试次数、屏幕数量、动作数量、章节内容
screen_completed 完成进度事件 章节编号、章节名称、尝试次数、步数、章节内容
3D 无尽跑酷游戏 run_completed 游戏循环完成情况 收集的金币数，得分 跑步时长、从喷气背包中收集的硬币数、跑步开始时使用的助推器、使用的冲浪板数、使用的磁铁数、使用的跳跃器数、使用的喷气背包数
开放世界动作类角色扮演游戏 areaExplorationProgress 完成进度事件 击败的敌人数量、收集的药水数量 区域编号、区域名称、进度百分比
questCompleted 游戏循环完成 不适用 任务名称
weaponUnlocked 游戏内精彩瞬间 不适用 武器名称、武器等级
chestUnlocked 游戏内精彩瞬间 收集的增强矿石
带有装饰性元数据的休闲谜题 puzzleCompleted 游戏循环完成 / 进度事件完成 收集的金币数、收集的道具数 移动次数，是否使用过管家的礼物？关卡类型、关卡编号、使用的彩色助推器、使用的炸药
cardsCollected 游戏内精彩瞬间 1 星卡、2 星卡、3 星卡、卡片总数 专辑编号、专辑名称
街机竞速 raceCompleted 游戏循环完成 排名、使用 NOS 的次数、比赛时间 比赛类型、评分、所用车辆
carUpgraded 游戏内精彩瞬间 升级的车辆特征、旧级别 / 值、新级别 / 值 汽车类型、当前车库等级
第三人称大逃杀射击游戏 matchCompleted 游戏循环完成 淘汰数、爆头数、荣誉值 匹配类型、生存时间
电子竞技管理模拟游戏 matchCompleted 游戏循环完成 结果、进球数、进球 对阵队伍的名称、比赛队伍的名称
trainingCompleted 游戏内精彩瞬间 已完成的练习、teamplay_form_attack、teamplay_form_defense、teamplay_form_possession、teamplay_form_condition

progressUpdate 个活动

如果您的游戏具有主要进度机制，请使用此事件发送玩家的当前进度。该事件具有一个预定义属性“currentProgress”，其类型为 INT 或 STRING。使用此属性发送当前进度的值，因为这是游戏玩家资料的游戏统计数据界面中显示的唯一值。

由于玩家可以根据游戏中的当前进度比较自己的个人资料，因此在首次集成后，及时获取当前进度值非常重要。为了向玩家准确展示当前进度，您应在每次游戏会话开始时以及当前进度更新时发送 progressUpdate 事件。

示例
游戏类型 `progressUpdate` 事件的 currentProgress 属性
线性推进益智游戏 当前章节号或关卡号
3D 无尽跑酷游戏 最高得分、当前助力器余额
休闲益智 当前关卡编号、首次尝试获胜次数、已完成区域数量、已完成的收集数量
街机竞速 当前关卡号、币种余额
开放世界动作类角色扮演游戏 当前角色等级、当前等级编号
第 3 人称射击游戏 当前关卡编号
电子竞技模拟 经理级别编号、俱乐部级别编号

集成详情

API 端点和 SDK 可用于收集早期反馈，并将于 2026 年 7 月开始正式发布 (GA)。请参阅时间轴

本部分介绍了如何在客户端集成和服务器端集成中构建事件并发送它们。

何时应发送数据

灵活事件表示与游戏循环完成或特定游戏时刻相关的游戏内操作。请在这些事件发生后立即提交。例如，在游戏循环完成时立即提交游戏循环完成事件。

progressUpdate 事件表示玩家的当前进度级别。 在以下情况下，应使用此事件发送进度统计数据：

  1. 每当当前进度有更新时，立即发送最新值
  2. 每当玩家启动游戏时，以确保玩家始终拥有此统计数据。

集成路径

集成方式有两种：客户端集成和服务器到服务器集成。

服务器到服务器集成

借助公共 API 端点，您可以使用以下配置在请求载荷中发送事件：

路径参数
参数 数据类型 说明
playerId 字符串 玩家的 PGS ID。

授权和身份验证

服务器到服务器 API 调用遵循使用 OAuth 2.0 的标准对 Play 游戏服务的服务器端访问指南。请求必须包含使用 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 event：请求正文

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 的客户端集成涉及在触发点使用 Java 或 Csharp（具体取决于 SDK）构建事件对象，并使用 SDK 提供的上传函数发送这些对象。

同样，对于 progressUpdate 事件，请使用 currentProgress 属性记录更新后的进度，并使用 SDK 提供的上传功能发送这些属性。

事件

PlayerGameEvent 的客户端集成如下：

构建灵活的播放器游戏事件

Java


// 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 ...

Unity


// 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 ...

C++


// 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 玩家游戏事件

Java


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

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

Unity


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

C++


PgsPlayerGameEvent* progress_event = PgsPlayerGameEvent_create("progressUpdate");
if (progress_event != nullptr) {
   PgsPlayerGameEvent_putLong(progress_event, "currentProgress", 52);
}
记录事件并上传

Java


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

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

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

Unity


// 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();

C++


// 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);

时间轴

日期 Game Stats API 集成 游戏统计数据配置
2026 年 6 月
  • 开发者可以开始规划数据模型
 不适用
2026 年 7 月
  • API 已面向所有开发者正式发布 (GA)，可开始集成
  • 根据提供的架构和配置验证传入的数据
  • 用于提供事件架构和统计信息配置的配置 API
2026 年 8 月 不适用
  • Play 管理中心体验已正式发布，支持 CSV 上传
2026 年 9 月 不适用
  • 玩家开始在玩家资料中看到游戏统计数据