Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

游戏统计数据

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

不需要购买（例如，购买宝石），也就是说，它们不应因任何应用内购交易而更新。
不需要观看广告，也就是说，不应因观看广告而更新。
不是游戏的常规使用情况（例如，打开游戏；使用设置）。
不包含个人数据和敏感用户数据（根据 Play 政策的定义），包括用户 ID、密码、精确位置数据或健康数据，也不包含任何冒犯性、亵渎性、露骨色情、暴力或仇恨内容。
面向所有用户提供（例如，不是特定于团队的操作，也不是仅面向特定级别的用户提供或仅限时提供给 liveops 等）

集成步骤

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

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

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

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

集成包括以下步骤：

声明原始数据架构：在 Play 管理中心内使用 CSV 上传定义玩家事件。请参阅创建活动。
与游戏统计数据 API 集成：以声明的格式发送原始玩家数据，以实现灵活的玩家事件和progressUpdate事件。
- 使用客户端或服务器端集成发送所有已定义的事件。如需了解详情，请参阅播放器事件和 progressUpdate 事件的示例。
上传 ZIP 文件：提供 3 个 CSV 文件和所有用于定义 5 个重复统计数据和 1 个球员进度级别的图标图片文件。如需了解详情，请参阅 ZIP 文件指南。请提供以下详细信息：
- 用于重复统计信息的 CSV 文件：
  - 统计数据的唯一 ID。
  - 指定用于统计信息计算的事件标签。您无法在此处使用 progressUpdate 事件标签。
    - 指定要用于统计信息计算的属性标签。此值必须是指定事件的属性。
    - 指定汇总类型（SUM、MAX、MIN 或 COUNT），以确定如何计算所选属性标签的统计数据。
    - 指定一个可选的过滤条件，以便仅在满足该条件时计算逻辑。定义属性和事件标签、运算符（=、<、<=、>= 或 >）以及阈值。
  - 包含一个布尔值标志，用于指示相应统计数据是否可用于竞争性功能。
  - 如果该功能可用于竞技功能，则为真实玩家设置的每小时最低限额和最高限额。这样一来，我们就能识别出在参加联赛和社交挑战等功能时可能存在滥用行为的玩家。
  - 为玩家看到的统计数据提供唯一的显示名称。
  - 提供描述统计信息的唯一文本。此说明应详细说明玩家如何获得该统计信息，并且会显示在玩家的游戏玩家个人资料界面中。
  - 在 CSV 文件中输入确切的图标文件名，以提供代表相应统计信息的唯一图标。
  - 提供一个可选输入，用于指明增加值或减少值对玩家来说是好是坏。此输入将用于庆祝玩家的动作。
  - 为统计信息提供可选的计量单位，例如公里、英里和秒。
- 球员进度统计信息的 CSV 文件：
  - 为玩家看到的玩家进度提供唯一的显示名称。
  - 提供表示统计数据的唯一图标。
  - 为进度统计信息提供说明。
  - 提供一个可选输入，用于指明增加值或减少值对玩家来说是好是坏。仅当 currentProgress 属性的类型为 INT 时，此输入才会用于庆祝玩家的动作。
  - 为统计信息提供可选的计量单位，例如公里、英里、秒。
- 本地化 CSV 文件：为所有统计信息提供本地化显示名称。
  - 为每种本地化版本添加一行。
  - 使用之前在 CSV 中添加的统计信息显示名称字符串来唯一标识要添加本地化信息的统计信息。
  - 从语言代码列表中指定语言。
  - 添加指定语言的显示名称本地化。
  - 为指定语言的统计信息说明添加本地化。

规划架构

您可以使用游戏统计数据 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。您应使用此属性发送主要进度机制中玩家进度的当前值。如果您使用此事件，则必须提供预定义的“currentProgress”属性，并且必须使用此属性定义进度统计信息。

您可以将游戏中的其他进度系统（例如 lifetime highest score 或 current coin balance）的当前值作为此事件的其他属性发送。

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

示例

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

配置统计数据

您需要通过定义每项统计数据的计算逻辑和显示信息来配置重复性统计数据和进度统计数据。下面列出了不同游戏类型的重复性统计数据示例。重复性统计数据通常是指在极少数（3-4 个）游戏会话中，任何玩家的统计数据都会反复更新，并且与核心游戏循环相关联。

游戏名称	游戏统计信息的显示名称	活动属性	计算逻辑 [aggregation]	过滤
3D 无尽跑酷游戏	完成的跑步活动	event run_completed 的任何属性	数量	所有值 [无过滤条件]
	收集的金币数	事件 run_completed 的 coins_collected 属性	总和	不适用
	收集的密钥	事件 run_completed 的 keys_collected 属性	总和	不适用
	最高跑步得分	event run_completed 的 score 属性	Max	不适用
	已完成的高金币跑	事件 run_completed 的 coins_collected 属性	数量	Value > 5000
线性推进益智游戏	已完成的章节数	事件 chapter_completed 的任何属性	数量	所有值 [无过滤条件]
	已完成的界面	事件 screen_completed 的任何属性	数量	所有值 [无过滤条件]
	首次尝试时完成的章节数	事件 chapter_completed 的 Num_try 属性	数量	Num_try = 1
	首次尝试时完成的界面	事件 screen_completed 的 num_try 属性	数量	Num_try = 1
开放世界动作类角色扮演游戏	已完成的挑战任务	event quest_completed 的任何属性	数量	所有值 [无过滤条件]
	探索过的区域	area_exploration_progress 事件的 Perc_progress 属性	数量	值 = 100
	解锁的剑	事件 weapon_unlocked 的 Weapon_type 属性	数量	值 = “sword”
	击败的敌人数量	event area_exploration_progress 的 Enemies_defeated 属性	总和	不适用
	收集的生命药水数量	活动 chest_unlocked 的 Enhancement_ores 属性	总和	不适用
休闲益智	已完成的关卡	level_completed 事件的任何属性	数量	所有值 [无过滤条件]
	首次尝试时通过的关卡数	level_completed 事件的 Num_try 属性	数量	值 = 1
	使用的颜色增强道具	level_completed 事件的 color_booster_used 属性	总和	不适用
	使用的炸弹助推器	level_completed 事件的 Bomb_booster_used 属性	总和	不适用
	收集的卡片	event cards_collected 的 Total_cards 属性	总和	不适用
街机竞速	赢得的比赛数	race_completed 事件的名次属性	数量	值 = 1
	最快比赛	race_completed 事件的 race_time 属性	最小值	不适用
	NOS 使用情况	事件 race_completed 的 NOS_used 属性	总和	不适用
	使用 Mustang 完成的赛事	事件 race_completed 的 Car_type 属性	数量	值 = “Mustang”
	汽车升级	事件 car_upgraded 的任何属性	数量	所有值 [无过滤条件]
第三人称大逃杀射击游戏	获胜场次	match_completed 事件的任何属性	数量	Match_result = TRUE
	总消除数	活动 match_completed 的 eliminations 属性	总和	不适用
	最长存活时间	event match_completed 的 survival_time 属性	Max	不适用
	头像总数	event match_completed 的头像属性	总和	不适用
	技能总价值	event match_completed 的 skill_value 属性	总和	不适用
电子竞技管理模拟游戏	获胜场次	事件 match_completed 的结果属性	数量	结果 = “胜出”
	总进球数	event match_completed 的 Goals_scored 属性	总和	不适用
	赢得的硬地比赛	事件 hard_match_completed 的结果属性	数量	结果 = “胜出”
	净胜球数最多的胜场	event match_completed 的 Goal_difference 属性	Max	结果 = “Won”
	训练练习总数	event training_completed 的 drills_done 属性	总和	不适用
	已完成的训练总数	event training_completed 的任何属性	数量	不适用

集成详情

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

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

何时应发送数据

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

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

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

集成路径

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

服务器到服务器集成

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

路径参数

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

授权和身份验证

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

客户端实现

如需了解适用于您平台的“游戏统计数据”客户端实现，请参阅以下资源：

里程碑

日期	游戏统计数据 API 集成	游戏统计数据配置
2026 年 9 月	不适用	玩家开始在玩家资料中看到游戏统计数据。针对测试账号测试统计信息草稿配置。