集成游戏统计数据

本文档介绍了如何使用 Google Play 管理中心将游戏统计数据集成到游戏中。本文介绍了基本的 CSV 和 ZIP 文件格式，并说明了如何创建、导入和管理这些文件。

创建事件

如需为未发布的新游戏创建活动，请完成以下步骤：

  1. 创建事件 CSV 文件 PlayerGameEvent.csv
  2. 在 Google Play 管理中心内，选择一款游戏。
  3. 在 Play 游戏服务 - 游戏统计数据页面（扩大用户群 > Play 游戏服务 > 设置和管理 > 游戏统计数据）中，选择设置事件。
  4. 在活动配置页面中，拖放要上传的 CSV 文件。
  5. 创建赛事后，您需要设置统计数据

设置统计数据

创建活动后，您需要设置统计信息：

  1. 创建包含统计信息、本地化文件和图标文件的 ZIP 文件有关统计信息的 ZIP 文件指南。
  2. 在 Google Play 管理中心内，选择一款游戏。
  3. 在 Play 游戏服务 - 游戏统计数据页面（扩大用户群 > Play 游戏服务 > 设置和管理 > 游戏统计数据）中，选择设置统计数据。
  4. 在游戏统计数据配置页面中，放置 ZIP 文件以进行上传。
  5. 上传所有统计数据后，您就可以发布游戏了。

测试版游戏统计数据

如需验证游戏统计数据是否按预期运行，请按照以下步骤进行测试：

  • 设置内部测试轨道。
  • 为测试人员向游戏项目添加测试账号。
  • 使用 Play 游戏应用为其中一个测试账号创建 Play 游戏服务玩家资料。
  • 使用您创建 Play 游戏服务玩家资料时所用的同一测试账号打开游戏。
  • 验证在游戏启动时，屏幕上是否会显示 Play 游戏服务 的“欢迎消息框”，以确认自动身份验证成功。
  • 测试账号用户可以玩游戏来触发事件。检查 API 响应，了解事件是否已记录。

发布游戏统计数据

完成测试后，您必须发布游戏。 所有游戏活动和统计数据也会随之发布。

如需发布，请按以下步骤操作：

  1. 在 Google Play 管理中心内，选择一款游戏。
  2. 在 Play 游戏服务 - 游戏统计数据页面（扩大用户群 > Play 游戏服务 > 设置和管理 > 游戏统计数据）中，点击查看并发布。
  3. 在 Play 游戏服务 - 发布页面（扩大用户群 > Play 游戏服务 > 设置和管理 > 发布）中，查看相应操作并修正问题。
  4. 点击发布。 所有游戏统计数据均已发布。

删除游戏统计数据

游戏统计数据发布后，便无法删除。

活动 CSV 文件指南

CSV 文件的第一行是标题行。您必须使用活动 CSV 文件（例如 PlayerGameEvent.csv）导入活动。

PlayerGameEvent.csv 格式

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

 Event Name,Property Name,Property Type

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

下表对这些字段进行了说明。

CSV 列标题 是必需还是可选 接受的值
活动名称 必需 最多 50 个字符

只能包含字母、数字和下划线。

如果使用特殊事件名称 progressUpdate，则必须包含一个名为 currentProgress 的 INT64 或 STRING 类型属性。
媒体资源名称 必需 最多 50 个字符

只能包含字母、数字和下划线。

每个事件中必须唯一：属性名称在同一事件中必须是唯一的。

请勿使用以下预留关键字： id、count、key、value、where、from、and、or、true 或 false。
媒体资源类型 必需 区分大小写的枚举字符串，与支持的数据类型之一匹配：INT64、DOUBLE、STRING、BOOL

PlayerGameEvent.csv 文件要求：

  • 该文件最多支持 20 个唯一事件名称，每个事件最多支持 20 个属性。
  • 文件内容不能为空，并且应至少包含 1 行。
示例表格
事件名称 属性名称 属性类型
matchCompleted 时长 DOUBLE
matchCompleted 击杀 INT64
matchCompleted isWinner BOOL
matchCompleted matchType STRING
itemCollected coinsAmount INT64
itemCollected weaponType STRING
progressUpdate currentProgress INT64

统计数据的 ZIP 文件指南

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

文件名 是必需还是可选 接受的值
RepetitiveStatsConfig.csv 必需 重复性统计数据是指玩家在游戏中定期执行的操作。
ProgressionStatConfig.csv 必需 进度统计信息表示玩家在游戏中的进度。
StatLocalizations.csv 可选 提供游戏统计数据名称和说明的翻译。
图标文件 必需 采用 512 x 512 PNG、JPEG 或 JPG 格式的图标。

ZIP 文件必须满足以下要求：

  • ZIP 文件大小限制：未压缩的总大小上限为 10 MB。
  • 文件数量上限：ZIP 归档文件中最多可包含 53 个文件（3 个 CSV 文件和 50 个图标）。
  • 组合统计信息上限：ProgressionStatConfig.csv 和 RepetitiveStatsConfig.csv 中的统计信息总数不得超过 50 个。
  • 支持的 CSV 文件： ProgressionStatConfig.csv、RepetitiveStatsConfig.csv 和 StatLocalizations.csv（可选）。 如果您只想上传进度统计数据，请勿在 ZIP 文件中包含重复的统计数据 CSV 文件；否则，控制台会发出错误。如果您只想上传重复性统计数据，也适用此方法。
  • 图标图片文件：PNG (.png) 或 JPEG (.jpg、.jpeg)。
    • CSV 中引用的所有图标都必须存在于 ZIP 文件的根目录中。
    • ZIP 文件中的所有图片文件都必须至少被一个统计数据引用。
  • 目录结构：所有文件都必须位于 ZIP 文件的根目录下。 不允许使用子目录。

RepetitiveStatsConfig.csv 格式

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

Stat Id,Event Name,Event Property Name,Aggregation Type,Stat Display Name,Stat Description,Filter Property,Filter Operator,Filter Value,Is Competitive,Min limit,Max limit,Icon File Name,Good value direction,Unit

下表对这些字段进行了说明。

CSV 列标题 是必需还是可选 接受的值
统计 ID 必需 最多 100 个字符

只能包含字母、数字和下划线。必须在游戏中的所有统计数据中是唯一的。
事件属性名称 必需 最多 50 个字符
统计数据的显示名称 必需 最多 50 个字符
统计信息的默认显示名称（默认语言区域）。在所有统计数据中必须是唯一的。
统计数据说明 必需 最多 500 个字符
统计信息的默认说明。
聚合类型 必需 最多 50 个字符
SUM、MAX、MIN、COUNT。
过滤媒体资源 可选 最多 50 个字符
必须是 PlayerGameEvent.csv 中定义的属性名称。
过滤条件运算符 可选 =, !=, >, <, >=, <=
过滤条件比较运算符。
过滤值 可选 与过滤属性进行比较。 过滤条件值必须为 INT64, DOUBLE, BOOL, STRING。
具有竞争力 必需 true, false
下限 当“Is Competitive”为 true 时为必需 竞争性统计数据的最低允许得分。
最大限制 当“Is Competitive”为 true 时为必需 竞争性统计数据的最高允许得分。
图标文件名 必需 包含在 ZIP 文件根目录中的图标图片的文件名。 不得与重复统计信息中使用的图标文件名冲突。
“性价比高”方向 必需 指定值越高 (INCREASING) 越好还是值越低 (DECREASING) 越好。
单位 可选 原始数值或时长值的计量单位。例如，KILOMETER、SECOND、PERCENTAGE、UNITLESS。

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

示例表格
统计 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,Event Property Name,Stat Display Name,Stat Description,Icon File Name,Good value direction,Unit

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

下表对这些字段进行了说明。

CSV 列标题 是必需还是可选 接受的值
统计 ID 必需 最多 100 个字符

只能包含字母、数字和下划线。必须在游戏中的所有统计数据中是唯一的。
活动名称 必需 最多 50 个字符

必须引用 PlayerGameEvent.csv 格式中定义的事件名称。
事件属性名称 必需 最多 50 个字符

必须是 PlayerGameEvent.csv 中定义的属性名称。
统计数据的显示名称 必需 必须是唯一名称。
统计数据说明 必需 最多 50 个字符
统计信息的默认说明。
图标文件名 必需 包含在 ZIP 文件根目录中的图标图片的文件名。 不得与重复统计信息中使用的图标文件名冲突。
“性价比高”方向 必需 指定值越高 (INCREASING) 越好还是值越低 (DECREASING) 越好。
单位 可选 原始数值或时长值的计量单位。例如，KILOMETER、SECOND、PERCENTAGE、UNITLESS。
示例表格
统计 ID 活动属性名称 统计数据的显示名称 统计数据说明 图标文件名 良好的价值方向
5 currentProgress 级别 玩家可以通过参加比赛来累积经验值并升级。 Level.png 增加

StatLocalizations.csv 格式

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

Stat Id,Stat Display Name,Locale,Localized Stat Display Name,Localized Stat Description

下表对这些字段进行了说明。

CSV 列标题 是必需还是可选 接受的值
统计 ID 必需 最多 100 个字符

只能包含字母、数字和下划线。必须在游戏中的所有统计数据中是唯一的。
统计数据的显示名称 必需 必须是唯一名称。
语言区域 必需 语言区域代码，例如 en-US。
请先为游戏添加翻译，然后再指定语言区域。请注意，您无法指定默认语言区域。

如需查看受支持的语言区域代码，请参阅 支持的语言列表。
本地化统计信息显示名称 可选 最多 50 个字符。相应语言区域的已翻译统计信息显示名称。
本地化统计信息说明 可选 不得超过 500 个字符。指定语言区域的已翻译统计信息说明。
示例表格
统计 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

图标文件

您在 .csv 文件中引用的图标必须存在于您当前导入的 ZIP 归档文件中。

图标验证规则如下：

验证属性 强制执行的限制条件 / 规则
文件大小上限 每个图标文件的最大大小为 1 MB（1,048,576 字节）。
维度 恰好为 512 × 512 像素（宽度 = 512，高度 = 512）
宽高比 严格的 1:1（方形宽高比）
允许的格式 PNG (.png) 和 JPEG (.jpg、.jpeg)
在 ZIP 中的位置 必须位于 ZIP 文件中的根目录下。
引用的检查 “图标文件名”列中指定的所有图标文件名都必须存在于 ZIP 文件中。
孤立检查 ZIP 中的所有图片文件都必须至少被一个统计数据引用。
冲突检查 ProgressionStatConfig.csv 中的图标文件名不得与 RepetitiveStatsConfig.csv 冲突。
视觉重复项 系统会标记重复的图标。

图标指南

图标需以 512 x 512 像素的 PNG、JPEG 或 JPG 格式创建。

所有语言区域均使用相同的图标，因此我们建议您不要在图标中添加任何文本或本地化内容。

单元规格

“单位”列用于控制如何为玩家设置原始统计值的格式和本地化。

数值统计属性（INT64、DOUBLE）

允许的单位值 示例原始值
（空） / 无单位 / 无 1234567
% / PERCENTAGE / PERCENT 0.857
距离/长度：厘米、米、公里、英尺、英寸、英里、码、毫米、纳米 15（公里）
速度：KILOMETER_PER_HOUR、METER_PER_SECOND、MILE_PER_HOUR 60（英里/小时）

非数字统计属性（STRING、BOOL）

单位列必须留空。