第2章 埋点方案设计模板

定义事件命名规范 · 属性字典 · 触发时机 · 上报策略

2.1 适用场景

场景	说明
新产品/新功能上线	需要从零搭建数据采集体系，定义关键行为事件与核心指标。
旧埋点重构/统一	历史埋点命名混乱、属性缺失或跨端不一致，需按规范重新设计。
跨团队协作埋点	产品、研发、数据、测试多方需要统一的方案文档做评审与验收依据。
第三方SDK接入	使用友盟、Firebase、Sensors Analytics 等工具时，提前设计事件与属性映射。

2.2 前置条件

• 需求文档已确认：产品PRD或数据需求清单经过评审，关键用户路径与核心指标已定义。
• 技术选型已确定：选定埋点SDK（如神策、GrowingIO、自研SDK）及数据仓库目标表结构。
• 命名规范基线已建立：组织级或项目级已发布《事件命名与属性字典编写指南》基础版。
• 角色分工明确：数据产品经理、前端/客户端开发、后端开发、测试工程师已到位。

2.3 操作步骤

埋点方案设计分为四个核心环节，按顺序执行，每个环节产出对应模板章节。

1. 定义事件命名规范 —— 统一事件ID、显示名称、分类标签。
2. 构建属性字典 —— 明确每个事件的公共属性与业务属性，含数据类型与枚举值。
3. 设定触发时机 —— 精确描述事件在什么条件下被采集（页面/点击/曝光/自定义）。
4. 配置上报策略 —— 确定上报方式、缓存机制、重试策略与优先级。

步骤1：定义事件命名规范

事件命名采用三段式结构：对象_动作_场景，全部小写，下划线分隔，禁止使用空格或驼峰。

字段	规则	示例
事件ID（event_id）	三段式，全局唯一，不超过64字符	product_click_list 、 order_submit_payment
显示名称（display_name）	中文，业务可读，不超过20字	商品列表点击、提交订单（支付页）
事件分类	page / click / exposure / custom	click
事件版本	从 v1 开始，变更属性或触发条件时递增	v1、v2

步骤2：构建属性字典

属性分为公共属性（所有事件共享）和业务属性（事件独有）。每行属性需填写：属性名、数据类型、必填/选填、枚举值/范围、示例值。

类别	属性名	类型	必填	枚举/范围	示例
公共	user_id	string	是	—	"u_10086"
公共	platform	string	是	ios / android / web / mini	"ios"
公共	app_version	string	是	语义化版本	"3.2.1"
业务	product_id	string	是	—	"prod_998"
业务	list_position	int	否	≥0	3
业务	action_source	string	否	home / search / recommend	"search"

属性字典需附带数据类型约束说明，例如：int 为 64 位整型，float 保留两位小数，string 不超过 256 字符。

步骤3：设定触发时机

触发时机决定了事件在什么精确条件下被采集。分为四类：

触发类型	描述	典型条件
页面触发	页面进入 / 离开 / 停留超时	onShow / onHide / 30s 无操作
点击触发	用户点击可交互元素	onClick / onTap / 长按
曝光触发	元素进入可视区域 ≥ 1s 且占比 ≥ 50%	IntersectionObserver / 曝光池检查
自定义触发	业务逻辑满足特定条件（如支付回调、API 响应）	onSuccess / onError / 定时器

# 触发时机配置示例（YAML 风格，非真实 SDK 配置）
event_id: product_click_list
trigger:
  type: click
  selector: ".product-item"          # Web 端
  android_view_id: "rv_product_list"  # Android 端
  ios_accessibility_id: "productCell" # iOS 端
  min_interval_ms: 2000               # 防止重复点击，单位毫秒

步骤4：配置上报策略

上报策略控制数据从端到服务器的传输行为，需在方案中明确以下参数：

• 上报方式：实时 / 批量（批量阈值建议 50 条或 30s 间隔，以先到为准）。
• 缓存机制：本地 SQLite 或文件缓存，最大缓存量 20MB，超限按 FIFO 丢弃旧数据。
• 重试策略：失败后最多重试 3 次，间隔 2s / 5s / 15s，仍失败则写入失败日志。
• 优先级：核心事件（如支付、注册）使用 high 队列，非核心事件使用 low 队列。
• 采样率：高流量事件可配置采样，如 0.1（10%），并上报采样标识 is_sampled: true。

# 上报策略示例（JSON 片段）
{
  "event_id": "order_submit_payment",
  "upload_strategy": {
    "mode": "realtime",
    "retry": {
      "max_attempts": 3,
      "backoff_ms": [2000, 5000, 15000]
    },
    "cache": {
      "max_size_mb": 20,
      "overflow_policy": "fifo"
    },
    "priority": "high",
    "sampling_rate": 1.0
  }
}

图2-1 埋点方案设计四步流程

2.4 输入输出物

类型	名称	格式/载体	责任人
输入	产品PRD / 数据需求清单	Confluence / 飞书文档	产品经理
输入	埋点SDK技术文档	Wiki / 在线文档	技术负责人
输出	埋点方案设计模板（本章产出物）	Excel / 在线表格 / JSON Schema	数据产品经理
输出	事件定义与属性字典核对清单	可勾选 Checklist	数据产品经理 + 测试

2.5 责任边界

• 数据产品经理：主导方案设计，完成事件命名、属性定义、触发时机编写，组织评审。
• 前端/客户端开发：评审触发时机与上报策略的技术可行性，确认选择器与视图ID。
• 后端开发：确认服务端事件（如API回调）的触发条件与数据格式。
• 测试工程师：根据方案编写埋点用例，执行验收测试，输出测试报告。
• 数据分析师：审核属性字典是否满足分析需求，提出补充字段。

2.6 记录材料

方案评审与变更过程必须留存以下材料，归档至项目共享空间：

材料名称	包含内容	归档位置
埋点方案 V1.0（初始版）	事件定义表 + 属性字典 + 触发时机 + 上报策略	Confluence “埋点方案” 空间
评审纪要	评审日期、参与人、修改意见、结论	项目周报 / 会议记录
变更日志	变更版本、日期、修改人、修改内容简述	方案文档末页 / 在线表格
测试验收报告	用例列表、通过率、未通过项及原因	测试管理平台

2.7 异常处理

异常场景	处理措施	责任人
事件ID与已有项目冲突	添加项目前缀（如 shop_product_click_list），并在命名规范中登记前缀表。	数据产品经理
属性数据类型无法兼容多端	统一使用 string 作为传输类型，端上自行转换；或由后端做标准化清洗。	前后端开发协商
触发时机在低端设备无法实现	降级为页面级点击监测，或使用飞控采样。	客户端开发
上报队列积压导致丢失	提高批量阈值，开启本地缓存持久化，增加失败日志告警。	后端/数据工程师
产品需求在埋点开发中变更	发起方案变更评审，更新版本号，同步更新测试用例。	数据产品经理

2.8 验收标准

埋点方案设计完成后，须通过以下七项验收检查方可进入开发阶段：

#	验收条目	通过条件
1	事件命名合规性	所有事件ID符合三段式命名，无驼峰、无空格、无状态词。
2	属性字典完整性	每个事件至少包含 1 个业务属性；公共属性清单全部覆盖。
3	触发时机精确性	每个事件有且仅有一个触发类型，条件描述无歧义。
4	上报策略可执行	策略参数（重试次数、缓存上限、采样率）均填写具体数值。
5	多端一致性	同一事件在 iOS / Android / Web 三端的 event_id 和属性名完全一致。
6	版本与变更记录	文档首部标注版本号、最后修改日期；变更日志不为空。
7	评审签字确认	产品、技术、测试三方在评审纪要上签字或在线确认。

---

— 第2章 结束 —