集成游戏统计数据

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

创建或导入事件

首次使用 Google Play 管理中心添加事件的方式有两种：

创建活动

如需为游戏创建活动，请完成以下步骤：

  1. 在 Google Play 管理中心内，选择一款游戏。
  2. 在 Play 游戏服务 - 游戏统计数据页面（扩大用户群 > Play 游戏服务 > 设置和管理 > 游戏统计数据）中，依次选择添加事件 > 创建事件。
  3. 在创建事件页面中，填写表单。
  4. 点击保存更改。

导入活动

如需一次为您的游戏添加多项活动，请按以下步骤操作：

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

创建或导入统计信息

首次使用 Google Play 管理中心添加统计信息的方式有两种：

创建统计项

如需为游戏创建统计信息，请完成以下步骤：

  1. 在 Google Play 管理中心内，选择一款游戏。
  2. 在 Play 游戏服务 - 游戏统计数据页面（扩大用户群 > Play 游戏服务 > 设置和管理 > 游戏统计数据）中，依次选择添加统计数据 > 创建统计数据。
  3. 在创建统计信息页面中，填写表单。
  4. 点击保存更改。
  5. 创建统计信息后，请发布您的游戏。

导入统计信息

如需导入统计信息，请按以下步骤操作：

  1. 根据统计数据 ZIP 文件指南，创建包含统计数据、本地化内容和图标文件的 ZIP 文件。
  2. 在 Google Play 管理中心内，选择一款游戏。
  3. 在 Play 游戏服务 - 游戏统计数据页面（扩大用户群 > Play 游戏服务 > 设置和管理 > 游戏统计数据）中，依次选择添加统计数据 > 通过 ZIP 导入。
  4. 在游戏统计数据配置页面中，拖放 ZIP 文件即可上传。
  5. 上传所有统计信息后，发布您的游戏。

测试游戏统计数据

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

  • 打开 Google Play 商店应用。
  • 在 Google Play 商店应用中登录您的 Play 游戏玩家资料。
  • 在玩家资料中查看游戏统计数据。

查看设备上的日志

如需验证游戏统计数据是否按设计运行，请在设备中开启日志：

  1. 在设备上启用 adb 调试，并在终端中运行以下命令：

    adb shell setprop log.tag.Games INFO
adb logcat -s "PlayGamesServices[GameStatsAgent]:I"

  2. 验证是否显示成功日志消息，如以下示例所示：

    Successfully uploaded batch of X events.

    注意：由于该 API 支持部分上传，因此此信息日志表示批次已处理。如果批处理中的任何个别事件未通过架构验证，此消息前面会显示错误日志。

  3. 如果任何提交的事件未通过验证，您会看到一条详细说明失败原因的出错提示：

    BatchRecordEvents validation failed for X event(s): ...

发布游戏统计数据

完成测试后，您必须发布游戏。 所有游戏事件和统计信息也会随之发布。

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

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

修改游戏统计数据

如果您已有一些游戏统计数据，并且想进行修改，请执行以下操作：

  1. 在 Google Play 管理中心内，选择一款游戏。
  2. 前往 Play 游戏服务 - 游戏统计数据页面（扩大用户群 > Play 游戏服务 > 设置和管理 > 游戏统计数据）。
  3. 如需修改活动，请执行以下操作：
    1. 在事件配置部分中，选择一个事件。
    2. 您可以添加或删除事件属性。
      • 您无法修改事件名称。
    3. 点击保存更改。
  4. 如需修改统计信息，请执行以下操作：
    1. 在游戏统计数据配置部分，选择一项统计数据。
    2. 您可以修改统计数据名称、统计数据说明和图标文件名字段。
      • 您无法修改统计数据 ID 和进度方向。 统计单位和关联事件详情。
    3. 点击保存更改。
  5. 在 Play 游戏服务 - 游戏统计数据页面中，修改后的统计数据处于可供测试人员使用状态。
  6. 测试统计信息后，点击检查并发布。 这将重新发布您的游戏以及所有更新后的统计信息。

删除游戏统计数据

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

您可以删除处于可供测试人员使用状态的事件或统计信息。

  1. 在 Google Play 管理中心内，选择一款游戏。
  2. 前往 Play 游戏服务 - 游戏统计数据页面（扩大用户群 > Play 游戏服务 > 设置和管理 > 游戏统计数据）。
  3. 如需删除活动，请执行以下操作：
    1. 在事件配置部分中，选择一个事件。
    2. 点击删除活动。
  4. 如需删除 Stat，请执行以下操作：
    1. 在游戏统计数据配置中，选择要删除的统计数据。
    2. 点击删除游戏统计数据。

事件 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 duration 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 文件；否则，Play 管理中心会发出错误。如果您只想上传重复性统计信息，也同样如此。
  • 图标图片文件：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 个字符

必须引用 PlayerGameEvent.csv 格式中定义的事件名称。
事件属性名称 必需 最多 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 duration MAX 最长匹配生存 这表示玩家在任何比赛中的生存时间 isWinner = TRUE TRUE 0 50 stat1.png 下降 秒
2 matchCompleted isWinner COUNT 获胜的对局数 这表示玩家赢得的比赛场数 isWinner = TRUE TRUE 0 50 stat3.png 增加
3 matchCompleted 击杀 SUM 1 对 1 比赛击杀数 1 对 1 比赛中的击杀数 matchType = “1-on-1” FALSE stat4.png 增加
4 itemCollected coinsAmount SUM 收集的金币总数 玩家在比赛中收集金币 weaponType = "sword" FALSE stat2.png 增加

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 个字符
统计信息的默认说明。
图标文件名 必需 ZIP 文件根目录中包含的图标图片的名称。 不能与重复统计数据中使用的图标文件名冲突。
价值方向良好 必需 指定值越高 INCREASING 还是越低 DECREASING 越好。
单位 可选 原始数值或时长值的计量单位。例如，KILOMETER、SECOND、PERCENTAGE、UNITLESS。
示例表格
统计数据 ID 事件属性名称 统计数据显示名称 统计信息说明 图标文件名 价值方向正确
5 currentProgress 级别 玩家通过参加比赛积累经验值并升级。 Level.png increasing

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 Survie du match le plus long Cela indique la durée de survie d'un joueur dans n'importe quel match.
4 收集的黄金总数 es Oro total recolectado La jugadora recoge monedas mientras juega en un partido
4 收集的黄金总数 fr Or 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
距离/长度：CENTIMETER、METER、KILOMETER、FOOT、INCH、MILE、YARD、MILLIMETER、NANOMETER 15（公里）
速度：KILOMETER_PER_HOUR、METER_PER_SECOND、MILE_PER_HOUR 60 (MILE_PER_HOUR)

时长统计信息属性 (DURATION)

格式类别值 允许的单位值 原始值示例 格式化输出示例
UNIT_BASED / DURATION 必需：SECOND、MINUTE、HOUR、DAY、WEEK、MONTH、YEAR 5400 秒（小时） 1.5 小时
COMPONENT_NUMERIC / HH:MM:SS / CLOCK Granularity（可选，默认值为 WHOLE_SECONDS）： WHOLE_MINUTES、WHOLE_SECONDS、MILLISECONDS_ONE_DIGIT、MILLISECONDS_TWO_DIGITS、MILLISECONDS_THREE_DIGITS 3661 秒 01:01:01
COMPONENT_TEXT / TEXT Smallest Unit（可选，默认值为 SECONDS）： SECONDS、MINUTES、HOURS、DAYS、MONTHS、YEARS 90000 秒 1 天 1 小时

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

单位列必须留空。