2. 埋点采集阶段前置检查：SDK版本核查、采集开关校验、采样率配置确认
前置检查是埋点数据质量的“第一道防线”。在埋点正式进入采集流程之前，必须对SDK版本、采集开关状态及采样率配置进行逐项核查。任何一项前置条件不满足，都可能导致数据丢失、重复或错乱，且后期回溯成本极高。
常见陷阱：许多团队将“SDK已集成”等同于“SDK版本正确”，忽略版本号校验；或将“采集开关默认开启”视为常态，导致测试环境数据污染生产环境。前置检查必须基于明确的配置清单，而非默认假设。
2.1 适用场景
- 新应用/新模块首次集成埋点时：SDK首次接入，需验证版本兼容性与基础配置。
- SDK版本升级或热更新后：生产环境SDK版本变更，需确认新版本未引入破坏性变更。
- 环境切换（测试→预发布→生产）：不同环境下的采集开关与采样率配置需重新校验。
- 常态化数据巡检：周期性检查线上环境SDK版本、开关状态与采样参数是否与预期一致。
2.2 前置条件
| 检查项 | 前置依赖 | 所需物料 |
|---|---|---|
| SDK版本核查 | 已获取 SDK 集成文档、版本变更日志 | 应用构建产物（APK/IPA/小程序包）、版本号查询工具或 API |
| 采集开关校验 | 服务端下发开关配置已生效 | 开关配置后台、客户端调试面板、抓包工具（如 Charles / Fiddler） |
| 采样率配置确认 | 采样策略文档、AB 实验分组信息 | 配置中心后台、日志抽样工具、数据量估算脚本 |
2.3 操作步骤
前置检查应按“版本 → 开关 → 采样”的顺序执行，避免因版本不对导致后续校验失败。
步骤 2.3.1：SDK 版本核查
- 获取预期版本号：从项目技术文档或版本管理平台（如 Git Tag、Jira 版本）中提取目标 SDK 版本。
- 读取实际集成版本：通过客户端日志、构建产物包名/版本字段或 SDK 自带的版本查询接口获取实际版本号。
- 比对差异：预期版本 vs 实际版本是否一致。若不一致，需确认是否存在灰度发布或热更新逻辑。
- 检查版本兼容性：重点核对 SDK 版本与后端 API、数据协议版本是否匹配。
步骤 2.3.2：采集开关校验
- 确认开关分组：获取当前用户/设备所属的开关分组（如测试组、对照组、全量组）。
- 验证开关状态：在客户端调试模式中打印开关状态，或通过抓包查看服务端下发的开关 JSON 中
enable_collection字段的值。 - 多场景验证：
- 开关开启 → 确认数据正常上报。
- 开关关闭 → 确认无任何数据上报。
- 开关动态切换 → 确认客户端能实时响应，无需重启应用。
- 环境隔离检查：测试环境开关不应影响生产环境数据，生产环境开关不应残留测试标记。
步骤 2.3.3：采样率配置确认
- 确认采样策略：固定采样率 vs 动态采样率，以及具体的百分比阈值（如 10%、50%、100%）。
- 验证配置生效：通过配置中心后台查看当前采样率参数，并在客户端日志中确认采样逻辑生效。
- 数据量估算：根据当前日活用户数及事件量，结合采样率，推算预期数据量范围，避免超出后端处理容量。
- AB 实验组校验：若采样率因实验分组而异，需逐组验证配置一致性。
高效技巧：将前置检查步骤封装为一个自动化测试脚本（如 Shell 脚本或 Python 脚本），每次构建后自动执行版本核对、开关状态拉取与采样率校验，并输出检查报告。
2.4 输入与输出物
| 类别 | 输入物 | 输出物 |
|---|---|---|
| SDK版本 | SDK 集成文档、版本变更日志、构建产物 | 版本比对结果表（版本号、兼容性结论） |
| 采集开关 | 开关配置后台面板、客户端调试日志 | 开关状态验证记录（开启/关闭/切换时效性） |
| 采样率 | 采样策略文档、配置中心参数 | 采样率配置确认单、数据量估算表 |
2.5 责任边界
- 客户端开发：负责集成与配置 SDK，提供版本查询接口，确保开关与采样参数在客户端侧正确响应。
- 服务端开发/运维：负责下发正确的开关配置与采样率参数，保障配置中心的高可用与一致性。
- 测试工程师：主导执行前置检查流程，记录检查结果，对不符合项发起缺陷或变更请求。
- 数据产品/数据分析师：提供预期的采样策略文档，参与数据量估算校验。
2.6 记录材料
埋点前置检查记录表（2025-07-08）
项目名称：XX App v4.2.0
检查人：张三
---
[SDK版本核查]
- 预期版本：v2.3.1 (com.example.sdk 2.3.1)
- 实际版本：v2.3.1 (com.example.sdk 2.3.1)
- 兼容性：正常
[采集开关校验]
- 测试环境开关分组：test_group_001
- 开关状态：开启（enable_collection: true）
- 关闭后检查：无数据上报（验证1分钟）
- 实时切换响应：是（开关变更后10秒内生效）
[采样率配置确认]
- 当前采样率：20%（固定采样）
- 日活用户预估：500万
- 预期每日事件量：约 200,000 条（按平均每人每日2条事件计算）
- AB实验组采样率：A组20%，B组50% （已验证）
结论：所有前置检查项通过，状态正常。2.7 异常处理
| 异常现象 | 可能原因 | 处理措施 |
|---|---|---|
| SDK版本不匹配 | 构建产物未更新、CDN缓存、混淆规则误改 | 回退版本或通知开发重新构建；清理缓存后重试 |
| 采集开关无法关闭 | 开关下发未覆盖所有客户端、客户端未监听配置变更 | 检查开关下发链路（服务端→CDN→客户端）；确认监听逻辑实现 |
| 采样率配置未生效 | 配置中心参数错误、客户端采样逻辑未读取最新配置 | 比对配置中心与客户端日志中的采样参数；检查配置拉取时机 |
| 采集开关状态与预期分组不一致 | 用户/设备分组标识错误、AB实验分组未同步 | 核对分组标识规则；同步实验管理系统与开关配置 |
2.8 验收标准
- SDK版本核对通过：实际版本号与预期完全一致，且版本与后端协议兼容。
- 采集开关状态正确：开关开/关两种状态下数据上报行为与预期一致，实时切换响应时间 < 30秒。
- 采样率配置准确：实际采样率与配置中心参数偏差 ≤ 1%，数据量估算在预期范围内。
- 检查记录完整：所有检查项均填写完毕并归档至项目管理系统。