埋点实施

简介

埋点实施是将标准化的采集方案自动转化为项目源码中的埋点代码，并自动完成 SDK 接入与配置的过程。

埋点实施会扫描识别当前项目的技术栈（比如 Android 项目、iOS 项目），自动安装 SDK 并配置接收地址，并对埋点方案进行插码埋点。

核心依赖 Skill：sensors-tracking

实施前准备

• 采集方案文件（推荐 Excel）：包含事件名、属性名、属性类型、触发时机等。注意：仅纳入本次需实施的自定义事件/属性，切勿混入 $ 开头的预置事件/属性（如 $AppStart、$title），否则会导致后续元数据校验失败。
• 目标项目代码目录：AI 将读取该目录下的源码并完成插桩，请确保具备读写权限。
• 数据接收地址（server_url）：必须包含 project 参数（例：https://example.com/sa?project=default）。注：此地址用于 SDK 上报，可能与 Sensors CLI 接口地址不同，但须同属一套神策环境。
• 神策平台环境：方案中的事件与属性建议已在平台创建；神策 SA 版本需 ≥ 3.0.1（建议 3.0.4 及以上，以支持元数据校验）。

埋点实施

方式一：自然语言发起（推荐）

💬 用户指令： “请使用 sensors-tracking 对当前项目做埋点代码实施，采集方案为 demo/tracking-plan-demo.xlsx，数据接收地址为 https://sdk-product-datasink.sensorsdata.cn/sa?project=xxx。”

注意，“当前项目”也可直接使用当前的项目名称，比如 “对 AppMall 项目做埋点代码实施”。

方式二：快捷命令

/sensors-tracking implement --plan <采集方案文件路径> --server-url <数据接收地址>

比如在 Codex 中使用 sensors-tracking对项目进行埋点：

埋点实施过程解析

发起指令后，AI 将自动执行以下标准化流水线。以“商城埋点方案一键落地”为例：

Step 1: 方案解析与真实框架识别

AI 首先解析 Excel 方案，并扫描当前项目代码。

• 核心特性（真实框架自适应）：AI 不会机械沿用方案表格中的“平台=Web”字段，而是依据真实代码框架进行判定。例如，若项目是编译为 Android，AI 会精准识别为 Android，从而选择正确的 SDK 接入方式与插桩逻辑，规避“按错端实施”导致的上报异常。

解析埋点示例：

Step 2: 元数据一致性校验（安全拦截）

在写入代码前，AI 会通过 Sensors CLI 比对方案与神策平台的元数据。

• 核心特性（主动拦截）：若发现方案中的事件或属性在平台未创建，或数据类型不一致，AI 将主动暂停实施，绝不将错误埋点写入代码。
• 产物：输出 metadata-check-feedback.xlsx，逐条列明不一致项。您需要先修正平台或方案，再重新发起实施。

元数据校验不通过示例：

Step 3: SDK 接入与代码插桩

校验通过后，AI 将自动完成工程配置与代码修改：

• 安装对应平台的 Sensors SDK。
• 在初始化代码中配置您提供的 server_url。
• 根据方案中的“触发时机”（如“点击搜索按钮后”、“支付成功回调后”），在正确的业务代码位置精准插入 track 埋点代码。

完成示例：

核心交付产物

实施完成后，AI 会在项目根目录/analytics/reports 生成以下标准化交付物，可直接用于团队评审与验收：

 

产物名称	说明
埋点实施报告.html	核心交付物：包含实施范围、事件明细、代码改动 Diff、校验结果。含防伪签名（请勿手工修改，否则签名失效）。
metadata-check-feedback.xlsx	列明与神策平台不一致的事件或属性，指导修正。

常见问题

问题现象	解决方案
提示“数据接收地址缺少 project”	请检查 server_url 是否补全了 ?project=xxx 参数。
提示“CLI 环境与接收地址不一致”	确认 Sensors CLI 配置的环境与 server_url 是否同属一套神策环境（二者端口可能不同，但环境必须一致）。
提示“元数据校验接口不可用”	通常为神策 SA 版本低于 3.0.1，请联系管理员升级至 3.0.4 及以上。
要求确认框架？	这是实施前的必需确认项。请按真实项目框架选择，不确定时请研发协助确认。