数数埋点与数据分析
0. 本篇结论
本篇为 WEN-14 / B2-B 文档整理稿，状态为 draft。原文 producer_review_needed / canonical_candidate 保留，未取得该功能的产品批准凭证。规则编号、参考图与原候选内容不等于已上线行为。
来源为 project2-docs @ ec43be0e13c8624cfafd36c0fd803f3b89733fff 的 docs/planning/project2-game-feature-library-v1/features/analytics-tracking.md；获取时间 2026-10-13（UTC），通过 Git 固定提交阅读。共用归属、来源清单、冲突证据与待裁定项统一见运营总览。本篇后续“必须”“验收”均属于待审规则/预留验收，未在本批执行游戏或平台验证。
1. 功能定位
数数埋点系统负责定义 Project2 的用户识别、公共属性、事件名、事件属性、客户端/服务端采集边界、数据类型和校验流程，为留存、成长、经济、广告、活动、战斗和运营分析提供统一数据 contract。
2. 范围
In Scope：ThinkingData/数数接入原则、用户 ID 体系、公共事件属性、用户属性、事件数据、数据类型、客户端/服务端上报、时间校准、debug 校验。
Out of Scope：具体 BI 看板、投放归因平台配置、数据仓库建模、历史数据导入作业实现。
3. 玩家入口、解锁与提示
玩家无直接入口。埋点在登录、登出、道具变化、挂机领奖、任务、英雄升级、广告观看等行为发生时自动上报。开发和 QA 通过 debug 模式、日志和数据后台验证。
4. 核心玩家流程
- 客户端或服务端识别角色、账号、设备和服务器上下文。
- 行为发生时构造事件名、公共属性和事件属性。
- 客户端 SDK 或服务端 SDK 上报到数数接收端。
- 数据后台按
#account_id、#distinct_id、公共属性和事件属性归因。 - QA 和分析人员校验数据类型、ID 绑定、时区、事件时序和关键漏斗。
5. 核心规则
5.1 接入与字段规范
ANALYTICS-TRACKING-R-001：项目接入前需要确认 App ID、数据接收端地址、数据采集方案和需要接入的数据内容。ANALYTICS-TRACKING-R-002：事件名和属性名为字符串，可包含数字、字母和下划线，长度最大 50 个字符，不区分字母大小写；只有预置属性能以#开头。ANALYTICS-TRACKING-R-003：字段类型由首次入库类型决定。埋点设计阶段必须先确认数值、文本、时间、布尔、列表、对象和对象组类型，避免后续迁移。
5.2 账号、角色与设备 ID 绑定
ANALYTICS-TRACKING-R-004：不需要做数值运算的 ID 字段建议使用文本。角色 ID 即使由纯数字组成，也应优先按文本处理，避免大整数精度和无意义聚合问题。ANALYTICS-TRACKING-R-005：单账号单角色时，#account_id可使用玩家账号 ID；单账号多角色时，#account_id建议使用角色 ID，角色所属账号 ID 作为公共属性或用户属性记录。ANALYTICS-TRACKING-R-006：#distinct_id使用设备相关 ID、SDK 访客 ID 或业务访客 ID。首次上报#account_id时应同时携带#distinct_id，确保绑定成功。ANALYTICS-TRACKING-R-007：多端接入时，客户端和服务端在能获取两个 ID 的情况下均应同时携带#account_id和#distinct_id，避免数据孤岛。
5.3 时间、时区与服务端上报
ANALYTICS-TRACKING-R-008：海外多地区发行时，建议按当地时间和时区上报。客户端默认使用本机时间和时区，服务端需自行设置时区字段。ANALYTICS-TRACKING-R-009：客户端 SDK 初始化后、上报前应做时间校准，避免玩家修改本机时间导致事件时间超前或无法入库。ANALYTICS-TRACKING-R-010：服务端上报事件时，#time应为事件发生时间，#ip应取客户端 IP；正式环境推荐服务端 SDK + LogBus，长时间网络中断场景下不建议只用 batch 方式。
5.4 公共属性清理与上线校验
ANALYTICS-TRACKING-R-011：客户端公共事件属性在玩家退出登录后需要清除，避免下一个角色继承错误属性。ANALYTICS-TRACKING-R-012：上线前需要先跑少量测试数据，重点校验 ID 绑定、字段类型、公共属性、事件时序和 debug 模式可见性。
业务事件目录（WEN-14 draft）
本节集中原活动、公告、广告第 10.2 节候选行为；以下中文行为不是新事件名。原来源均为固定文档快照 ec43be0e13c8624cfafd36c0fd803f3b89733fff。除明确记录的历史名称外，正式 ASCII 事件名、参数、唯一业务标识、上报端与重复上报策略均缺证，需用户及 owner 确认，不补造命名。
| 业务归属 / 来源 | 原候选行为 | 埋点预留与边界 |
|---|---|---|
| 活动 第 10.2 节 | 活动曝光、进入、任务完成、奖励领取、过期未领、特权激活 | 业务开放/领奖条件归活动；客户端点击不能替代服务端奖励成功事实 |
| 公告 第 10.2 节 | 公告曝光、点击、关闭、平台分发结果；跑马灯触发、展示、打断、后台发送、敏感词过滤命中 | 业务通知归公告；平台分发与玩家曝光不混为一个成功指标 |
| 广告 / GM 第 10.2 节 | 广告请求、完成、失败、奖励发放；GM 使用、运营接口操作 | 广告完成和奖励到账分开；GM 审计不因存在分析事件而成立 |
| 本篇第 7、9、12、13 节 | 注册、登录/登出、item_change、AFK_reward、任务/日周活跃、英雄升级、广告；充值、抽奖、战斗、活动奖励尚待补表 | 历史名称只是原文声明；正式目录、字段及是否已有上线事件缺证 |
本批合并只移走上述三篇的重复行为清单，feature key、页面路径与规则编号保留。公告候选性能目标归公告第 13 节；本节不把业务指标自动转为埋点字段。命名冲突 task_week / daily_activity、AFK_reward 大小写、current_server_id 类型与用户 ID 口径见运营总览。
5.5 操作矩阵
N/A。当前不在策划案正文中复述核心玩家流程；进入 PLAN 时，仅对状态变化、消耗/产出、奖励发放、跨系统反馈或失败反馈补齐操作矩阵。
6. UI 状态与交互
6.1 界面图与交互说明
以下图片为待评审参考图，已按图片锚点和附近文字绑定到页面/状态；状态均为 仅参考，最终布局、尺寸、按钮位置和视觉风格以制作人/UI 评审确认为准。
图 01：ID体系常见疑问 / 一句话总结，事件行为会优先归因到#account_id所在用户身上
- 图状态：仅参考
- 关联页面 / 状态：ID体系常见疑问 / 一句话总结，事件行为会优先归因到#account_id所在用户身上
- 关联交互 / 状态说明：一句话总结，事件行为会优先归因到#account_id所在用户身上
6.2 页面结构与交互
玩家无 UI。开发调试需要日志开关、debug 模式和后台验证流程。数据异常时，应能通过设备 ID、角色 ID、服务器 ID 和事件时间定位。
6.3 UI 页面状态表
N/A。当前仅保留已绑定页面/状态的参考图和页面结构说明；具体可执行状态在 UI 评审或 UI brief 中确认。
7. 配置、数据与 Contract
本节只记录策划案需要的逻辑数据与跨部门 contract，不预设物理配置表、协议文件、service 文件或 仓库落点。正式命名、字段名、接口名、协议对象名、文件名和仓库落点进入执行前由 Work Package 的 contract-registry.yaml、execution brief 和对应执行任务确认。
7.1 策划数据需求
策划数据需求只描述逻辑数据域、逻辑字段或规则语义，不等同于配置表字段名、协议字段名或数据库字段名。正式字段命名进入 contract-registry.yaml、execution brief 和对应执行任务确认。
| 数据域 | 逻辑字段 / 规则 | 设计含义 | 必填 / 边界 | 产出责任 |
|---|---|---|---|---|
| 公共事件属性 | 账号标识、访客标识、服务器、设备、地区、时区、登录状态 | 定义所有事件共用的账号、设备、地区和服务器信息 | 进入执行前补齐默认值、边界和可选性 | Planning / Analytics |
| 用户属性 | 角色 ID、账号 ID、注册时间、累计登录、付费状态、等级段 | 定义角色生命周期和长期分群属性 | 进入执行前补齐默认值、边界和可选性 | Planning / Analytics |
| 事件目录 | 角色注册、登录登出、道具变化、任务、广告、挂机领奖、英雄升级 | 定义需要采集的业务事件和触发时机 | 进入执行前补齐默认值、边界和可选性 | Planning / Analytics |
7.2 运行时数据与接口需求
| Contract | 设计含义 | 使用方 | 说明 |
|---|---|---|---|
| 客户端埋点上报 | 采集 UI 行为、设备信息和客户端可见状态 | Frontend / Analytics | 需要时间校准和退出登录清理公共属性 |
| 服务端可信事件 | 采集经济变化、奖励发放、付费和反作弊相关事件 | Backend / Analytics | 服务端事件需带发生时间和必要上下文 |
| 数据校验流程 | 上线前验证字段类型、ID 绑定和事件时序 | Analytics / QA | 少量测试数据先行校验 |
7.3 跨部门 Contract 命名清单
| Contract 类型 | 逻辑对象 | 命名状态 | 阻塞阶段 | 说明 |
|---|---|---|---|---|
| 埋点事件 | 角色、道具、任务、广告、挂机、英雄成长等事件 | 待 PLAN 确认 | PLAN 前 | 正式事件名和参数进入 analytics contract |
| 用户属性 | 账号、角色、服务器、登录、付费和分群属性 | 待 PLAN 确认 | PLAN 前 | 字段类型首次入库前必须确认 |
| 错误码 | 埋点初始化失败、上报失败、字段类型冲突 | 待 PLAN 确认 | 执行前 | 用于调试和 QA 校验 |
8. 系统边界
| 方向 | 负责内容 | 备注 |
|---|---|---|
| Planning | 逻辑数据、数值、文本需求、资源需求 | 进入执行前由 PL 任务细化 |
| 服务端 | 协议、校验、持久化、奖励发放、幂等与安全 | 仅相关功能需要 |
| 客户端 | UI、交互、表现、本地状态、红点和跳转 | 仅相关功能需要 |
| 美术 | 图标、模型、特效、音频和导出资源 | 仅相关功能需要 |
| Ops / GM | 后台配置、运营投放、公告、补偿和数据看板 | 仅相关功能需要 |
客户端与表现
客户端需要接入 Unity SDK 或等价 SDK，设置公共属性、访客 ID、时间校准、debug 模式和日志开关。登录/登出时必须正确设置和清理公共属性。
美术与音频需求
无直接美术音频需求。
9. 数值、经济与奖励
本功能不直接发放奖励，但 item_change、活动奖励、挂机领奖、任务活跃、广告奖励、充值和抽奖等事件会记录经济变化。经济类事件必须能还原变更前数量、变化数量、变更后数量、道具 ID、变化途径和变化类型。
10. 异常、安全与运营边界
10.1 异常与安全
需要处理字段类型首次入库错误、ID 绑定失败、客户端时间被篡改、服务端事件缺少预置属性、公共属性未清理、批量上报丢失、海外时区错误、测试数据污染生产数据和多角色归因错误。
10.2 埋点与运营
本功能本身定义埋点 contract。后续新增功能必须在 PLAN 阶段明确是否新增事件、复用事件或更新公共属性，并在 contract-registry 中记录跨端事件名和属性名。
11. Feature Relations 与回归范围
Feature Relations
依赖 account-server-login、item-resource、home-idle-reward-science、task、character-hero、ads-sdk-gm-ops、activity-timeopen、battle-mission 和 recharge-giftpack。所有新增功能若有分析需求，都应引用本埋点 contract。
回归范围
以 Feature Relations 影响功能、核心玩家流程、配置与系统边界为基础；进入执行前由 PLAN / QA brief 细化最小回归范围。
12. 验收标准
12.1 关键验收结论
角色注册、登录、登出、道具变化、挂机领奖、任务、日/周活跃、英雄升级和广告事件能按约定事件名上报；公共属性齐全；ID 绑定正确；字段类型正确；时间和时区正确；客户端退出登录后公共属性清理；debug 模式可校验；服务端关键事件可追溯。
12.2 规则验收清单
规则正文集中在本篇第 5 节，原有 *-R-* 编号保留。原第 12.2 节逐条重复正文已合并到第 5 节；未来人工验收按这些编号记录结果，本批未验证也未勾选。共用规则按运营总览的归属引用，不另立副本。
12.3 执行层验收
- 如填写操作矩阵，成功路径、失败场景、玩家反馈和状态权威均已覆盖。
- 如填写 UI 页面状态表，页面 / 弹窗状态均已覆盖，或明确标记为
N/A。 - Section 7 中标记为 PLAN 前或执行前阻塞的 contract 已在
contract-registry.yaml、execution brief 或执行任务中确认。 - 相关 Feature Relations 回归通过。
13. 待澄清问题 / Open Questions
- Project2 最终用户识别口径是角色 ID、账号 ID，还是账号 + 角色双维度。
current_server_id在现有表中同时出现文本和数值口径，需要统一。task_week的活跃属性当前命名仍为daily_activity，是否应改为weekly_activity。AFK_reward是否需要统一为小写事件名，例如afk_reward。- 充值、抽奖、战斗开始/结束、关卡失败、活动奖励等事件是否已有后续表格，需要补齐。
14. 变更记录
| 日期 | 版本 | 修改人 | 变更摘要 |
|---|---|---|---|
| 2026-10-13 | draft / WEN-14 | AutoDev Symphony | 保留原审核状态与固定来源；明确共用归属及待裁定问题；合并重复规则清单与空图入口，不变更玩法 |
| 2026-06-16 | v0.2 | Codex | 补充规则编号、操作矩阵、UI 状态表、逻辑字段和执行层验收锚点 |
| 2026-06-16 | v0.1 | Codex | 按新版功能策划案模板重排章节；保留既有规则内容并映射参考图 |