第3章：数据埋点规范

Reach 触达指标的可信度完全建立在埋点数据的质量上。本章围绕前端埋点事件设计、服务端日志字段规范、SDK 接入要点与校验方法展开，定义统一的数据采集口径，确保触达量、送达率、展示时长等核心指标可量化、可复现、可归因。

3.1 埋点指标体系与口径

3.2 前端埋点事件设计

前端埋点采用事件驱动 + 生命周期模型，每个触达组件从创建到销毁经历 4 个核心阶段：

1. 下发阶段（reach.delivered）：服务端返回触达内容，SDK 接收并缓存。
2. 曝光阶段（reach.impression）：组件进入视口且满足面积 / 时长阈值时触发。
3. 交互阶段（reach.click / reach.dismiss）：用户点击内容或关闭触达。
4. 结束阶段（reach.completed / reach.timeout）：触达流程自然结束或被新触达覆盖。

{
  "event": "client.reach.impression",
  "timestamp": 1711584000123,
  "user": {
    "device_id": "d7a9f2e1b3c4",
    "user_id": "u_20240301_abc"
  },
  "reach": {
    "task_id": "task_1711584000",
    "template_id": "tpl_banner_v3",
    "strategy_id": "strategy_rank_01",
    "channel": "in_app_popup",
    "render_duration_ms": 45,
    "area_percent": 0.67,
    "session_seq": 2
  },
  "device": {
    "os": "iOS 17.3",
    "screen_w": 390,
    "screen_h": 844
  },
  "extra": {
    "ab_test_group": "treatment_A"
  }
}

3.3 服务端日志字段规范

服务端日志以 Apache Avro 格式序列化，保证字段类型严格一致。每个触达指令下发出时记录一条日志，关键字段如下：

3.4 SDK 接入要点

SDK 作为前端埋点与服务端日志的桥梁，接入时需重点校验 4 个规范：

1. 初始化时机：SDK 必须在应用启动后 500ms 内完成初始化，否则可能导致触达下发时埋点尚未就绪。
2. 事件去重：同一 task_id 的 impression 事件在 10s 内重复触发时，SDK 应自动丢弃（基于本地 buffer 去重表）。
3. 字段补齐：前端埋点必须带上 device_id、task_id、strategy_id 三个关联字段，缺失任一字段的事件在服务端 join 时直接降级。
4. 发送策略：事件先写入本地队列（上限 500 条），每 5s 批量上报一次；网络恢复后优先补发失败事件。

3.5 校验方法与验收标准

在埋点上线前，需通过以下 3 层校验才能放量：

3.6 埋点数据流架构

下图展示从触达下发到事件入库的完整数据流，包含前端埋点、服务端日志、SDK 校验层、ETL 清洗及最终进入指标看板的路径：

3.7 异常场景与业务动作

3.8 复盘分析要点

每次触达活动结束后，需从埋点质量维度完成以下复盘：

• 字段完整率：必填字段缺失是否在 0.1% 以内，若超标需回溯是 SDK 版本未升级还是网络断连导致。
• 事件重复率：同一个 task_id + event_type 在 30s 内重复计数占比，超过 5% 说明去重逻辑失效。
• 端到端延迟：服务端下发到前端曝光的时间差 P95，应 ≤ 3s；若劣化需检查 CDN 预热或渲染性能。
• 看板数据置信度：将看板中的触达展示量与第三方监测（如 AppsFlyer 回传）对比，偏差 ≤ 2% 视为可信。