游戏统计数据

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

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

集成步骤

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

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

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

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

集成包括以下步骤：

• 声明原始数据架构：在 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 发送两种类型的数据：玩家事件和用于玩家进度统计信息的预定义事件。

以下示例展示了不同类型游戏的玩家事件：

播放器事件

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

• 将事件定义为特定的游戏内时刻、游戏循环完成情况或进度里程碑：
  • 游戏循环完成情况，例如完成的比赛或跑步。
  • 进度里程碑，例如已保存区域的探索进度或已完成的关卡。
  • 由于重复性统计数据应真实反映玩家的可重复操作，因此所定义的事件应与核心游戏玩法相关联。
• 添加属性，以提供有关事件及其结果的背景信息，例如关卡编号、比赛类型、武器类型、武器数量、爆头次数、收集的币数、比赛结果、圈速或赛车类型。
• 在游戏会话中，发送事件的时间应尽可能早。例如，在游戏循环完成后立即发送游戏循环完成事件。

progressUpdate 个活动

如果您的游戏具有主要进度机制，请使用此事件发送玩家的当前进度。该事件具有一个预定义的属性“currentProgress”，其类型为 INT 或 STRING。您应使用此属性发送主要进度机制中玩家进度的当前值。如果您使用此事件，则必须提供预定义的“currentProgress”属性，并且必须使用此属性定义进度统计信息。

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

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

配置统计数据

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

集成详情

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

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

何时应发送数据

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

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

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

集成路径

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

服务器到服务器集成

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

路径参数

授权和身份验证

服务器到服务器 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
      }
    }
  ]
}

客户端实现

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

• Android
• Unity
• C++

里程碑