集成游戏统计数据

本文档介绍了如何使用 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. 上传所有统计数据后，发布游戏。

测试游戏统计数据

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

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

管理设备上的游戏统计数据公开范围以进行测试

当游戏在 Play 管理中心内可供测试人员使用后，请按以下步骤在设备上查看游戏统计数据：

  1. 清除 Google Play 商店缓存：

    1. 打开设备上的设置应用
    2. 依次点按应用 > Google Play 商店。
    3. 点按存储和缓存，然后点按清除缓存。

  2. 打开 Google Play 商店应用。

  3. 您可以使用跟踪游戏时长部分或玩家资料查看游戏统计数据：

方法 1：使用“跟踪游戏时间”部分

前往跟踪游戏时间部分，然后点按该部分以查看游戏统计数据。

游戏统计数据测试方法 1：使用“跟踪游戏时间”部分。
“个人中心”标签页上的“跟踪游戏时间”部分。

方法 2：使用玩家资料

  1. 点按我标签页，然后点按您的玩家资料。
  2. 前往游戏统计数据部分。
  3. 对于时间范围，请选择全部。
  4. 如果您的游戏未显示，请点按查看所有游戏。
  5. 选择游戏即可查看其统计数据。
游戏统计数据测试方法 2：使用玩家资料。
玩家资料中的“游戏统计数据”部分。

查看设备上的日志

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

  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. 如需删除统计信息，请执行以下操作：
    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 时长 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 个字符

必须引用 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 时长 MAX 最长匹配生存 表示玩家在任何比赛中的存活时间 isWinner = TRUE TRUE 0 50 stat1.png 减少 秒
2 matchCompleted isWinner COUNT 获胜场数 表示玩家赢得的比赛次数 isWinner = TRUE TRUE 0 50 stat3.png 增加
3 matchCompleted 击杀 SUM 单挑击杀数 在 1 对 1 比赛中获得的击杀数 matchType = “1 对 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 增加

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 Longest Match Survival es 在比赛中存活更长时间 Esto denota el tiempo de supervivencia de una jugadora en cualquier partido.
1 Longest Match Survival fr 最长比赛的存活时间 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 或“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）

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

时长统计属性 (DURATION)

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

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

单位列必须留空。