免费工具 数据埋点方案生成器：从行业模板开始，不用对着空表格想
埋点方案（也叫埋点需求文档、事件字典）就是一份清单：产品要上报哪些事件、每个事件带哪些属性、什么类型、从哪一端报。这里有 10 个行业模板，和 TapCub 产品里安装的事件定义是同一份；留下要的事件、补上自己的，导出 CSV 或 Markdown 交给开发。
- 10 个模板 · 111 个事件
- CSV + Markdown
- 本地生成
选模板，勾事件
标了「必需」的事件，是模板里看板和漏斗要用的。「上报端」写的是应该从哪里报：支付、退款这类只从服务端报，广告拦截和重试都影响不到。
搜索 / 看商品 → 加购 → 结账 → 支付 → 退款 的电商主线。事件名与「电商与收入」模块的默认映射一致（view_item / add_to_cart / begin_checkout / purchase / refund），装完该模块直接有数；purchase / refund 必须服务端上报，insert_id 用订单号去重。多门店 / 多店铺零售把门店当 group 主体。
一行一个事件：事件名 | 显示名 | 属性:类型, 属性:类型!。类型可写 string、number、boolean、array（也认「字符串」「数字」「布尔」「数组」），! 表示必填。事件名按 TapCub 事件目录的规则检查：小写字母、数字、下划线，字母开头，最多 40 个字符，不能以 $、_、tc_ 开头。
事件
9
属性
36
必需事件
4
只从服务端报
2
事件表
| 事件名 | 显示名 | 分类 | 必需 | 上报端 | 属性数 | 说明 |
|---|---|---|---|---|---|---|
search | 站内搜索 | 浏览发现 | 可选 | 网页、小程序、App | 2 | |
view_item | 看商品 | 浏览发现 | 必需 | 网页、小程序、App | 4 | |
add_to_wishlist | 收藏 | 浏览发现 | 可选 | 网页、小程序、App | 1 | |
add_to_cart | 加购 | 购物车 | 必需 | 网页、小程序、App | 4 | |
remove_from_cart | 移出购物车 | 购物车 | 可选 | 网页、小程序、App | 1 | |
view_cart | 看购物车 | 购物车 | 可选 | 网页、小程序、App | 2 | |
begin_checkout | 开始结账 | 下单支付 | 必需 | 网页、小程序、App | 3 | |
purchase | 支付成功 | 下单支付 | 必需 | 服务端 | 10 | 订单支付成功由服务端上报，insert_id = 订单号；revenue 为实付金额；多门店带 group=store:<门店ID> |
refund | 退款 | 售后 | 可选 | 服务端 | 3 |
属性表
写成 items[].price 的行，是数组属性里每个元素的字段。
| 事件名 | 属性 | 类型 | 必填 | 单位 | 可选值 | 说明 |
|---|---|---|---|---|---|---|
search | query | 字符串 | 必需 | — | — | |
search | results | 数字 | 可选 | — | — | 结果数，0 = 无结果搜索 |
view_item | item_id | 字符串 | 必需 | — | — | |
view_item | category | 字符串 | 可选 | — | — | |
view_item | price | 数字 | 可选 | 金额 | — | |
view_item | currency | 字符串 | 可选 | — | — | |
add_to_wishlist | item_id | 字符串 | 必需 | — | — | |
add_to_cart | item_id | 字符串 | 必需 | — | — | |
add_to_cart | quantity | 数字 | 可选 | — | — | |
add_to_cart | value | 数字 | 可选 | 金额 | — | |
add_to_cart | currency | 字符串 | 可选 | — | — | |
remove_from_cart | item_id | 字符串 | 必需 | — | — | |
view_cart | value | 数字 | 可选 | — | — | |
view_cart | items_count | 数字 | 可选 | — | — | |
begin_checkout | value | 数字 | 可选 | 金额 | — | |
begin_checkout | items_count | 数字 | 可选 | — | — | |
begin_checkout | coupon | 字符串 | 可选 | — | — | |
purchase | order_id | 字符串 | 必需 | — | — | |
purchase | revenue | 数字 | 必需 | 金额 | — | |
purchase | currency | 字符串 | 必需 | — | — | |
purchase | items_count | 数字 | 可选 | — | — | |
purchase | coupon | 字符串 | 推荐 | — | — | 订单级优惠券码；促销报表按此分组 |
purchase | payment_method | 字符串 | 可选 | — | wechat / alipay / card / cod / other | |
purchase | store_id | 字符串 | 可选 | — | — | |
purchase | items | 对象数组 | 推荐 | — | — | 订单明细 [{item_id, name, category, price, quantity, coupon?}]；缺失则商品报表 / 促销报表只能按订单级 coupon 统计 |
purchase | items[].item_id | 字符串 | 必需 | — | — | |
purchase | items[].name | 字符串 | 可选 | — | — | |
purchase | items[].category | 字符串 | 可选 | — | — | |
purchase | items[].price | 数字 | 可选 | 金额 | — | |
purchase | items[].quantity | 数字 | 可选 | — | — | |
purchase | items[].coupon | 字符串 | 可选 | — | — | |
purchase | promotion | 字符串 | 推荐 | — | — | 促销活动名（如 618 / 满减） |
purchase | discount | 数字 | 可选 | 金额 | — | 优惠金额 |
refund | order_id | 字符串 | 必需 | — | — | |
refund | revenue | 数字 | 必需 | 金额 | — | |
refund | reason | 字符串 | 可选 | — | quality / size / changed_mind / delay / other |
版本 v1.0更新于 更新记录
方案里每一部分是干什么的
多数团队两张表就够：一个事件一行、一个属性一行。负责人、上线版本、截图这些，在表格里加列就行。
必需事件
模板里的看板、漏斗、指标依赖它们。电商模板是 view_item、add_to_cart、begin_checkout、purchase 四个，少报一个，漏斗就有一步是空的。
上报端
事件应该从哪里报。网页和 App 记录的是人在屏幕上做了什么；服务端记录的是事实——付款、退款、续费——不能被广告拦截插件挡掉，也不能因为重试多算一次。
必填属性和推荐属性
必填属性是指标要读的（收入要 revenue 和 currency，去重要 order_id）；推荐属性能多出报表，比如订单明细 items 才有商品和促销报表。
只从服务端报的事件
用服务端 SDK 报，并把订单号 / 单据号当 insert_id，接口重试时不会多出一笔订单。
模板只是起点。永远不会分析的事件就删掉：多一个事件，就多一份测试、文档和维护。
从模板到开发能照着做的方案
第一版十分钟；然后和写埋点代码的同事过一遍。
-
1
选最接近的行业
网上卖货选电商，订阅制选 B2B / SaaS，靠表单和电话的选线索留资。以后可以叠加多个模板。
-
2
只留会用的事件
先点「只留必需」，再把你真正要回答的问题背后的事件勾上。事件少而定义清楚，比一长串没人维护的清单好用。
-
3
补上自己的事件
一行一个，带属性和类型。输入时就按 TapCub 事件目录的规则检查事件名。
-
4
导出交给开发
CSV 放进 Excel、飞书或腾讯文档表格，Markdown 贴到 Wiki 或代码评审里；也可以直接打开埋点代码生成器拿代码。
每一列写什么
列的含义和产品行业包的格式一致，这里写的方案和 TapCub 安装的定义一一对应。术语见埋点方案和事件属性。
- 事件名：每条事件存下来的主键。小写下划线、字母开头、最多 40 个字符；
$、_、tc_开头的保留给系统。 - 显示名：报表里给人看的名字，以后可以改；事件名不要改。
- 属性类型：字符串、数字、布尔，或者对象数组（比如订单明细）。网页统计脚本只收字符串、数字、布尔，数组放在服务端事件里报。
- 单位：金额标「金额」，一定和币种属性一起报；时长单位是秒。
| 列 | 含义 | 例子 |
|---|---|---|
| 事件名 | 代码里上报的名字 | purchase |
| 必需 | 看板和漏斗依赖它 | 必需 |
| 上报端 | 网页、小程序、App 或服务端 | 服务端 |
| 属性 | 事件里带的键 | revenue |
| 类型 / 单位 | 值怎么存 | 数字 · 金额 |
| 可选值 | 固定的取值范围（有的话） | wechat / alipay / card |
电商模板里的「支付成功」purchase
默认模板这样定义一笔已支付的订单，直接取自产品行业包。
| 属性 | 类型 | 必填 | 为什么要它 |
|---|---|---|---|
order_id | 字符串 | 必需 | 同时当 insert_id，接口重试不会变成第二笔订单 |
revenue | 数字（金额） | 必需 | 实付金额；收入报表、客单价都读它 |
currency | 字符串 | 必需 | 多币种时换算要用 |
items | 对象数组 | 推荐 | 订单明细（item_id、name、category、price、quantity），没有它商品报表只能看到订单 |
coupon | 字符串 | 推荐 | 促销报表按它分组 |
这里的 purchase、revenue、currency、order_id 也是电商收入报表的默认映射，按这个方案报的订单，不用额外设置就能进报表。
埋点方案常在哪里出问题
多数问题不是少了事件，而是事件数据不可信。
给已上线的事件改名
事件开始采集后，名字就是数据里的主键。要改就改显示名，否则每张图都会断成两截。
只在前端报支付
广告拦截、关页面、重复点击都会让前端的支付事件失真。付款由服务端报，用订单号去重。
一个按钮一个事件
button_1_click、button_2_click……没法分析。一个事件带一个属性（哪个按钮、哪个套餐），好画图也好维护。
属性里放原始个人信息
手机号、邮箱、用户输入的原文都不该进事件属性。需要识别就先哈希，否则不报。
同一套模板，产品里一键安装
这页的每个模板都是产品里的行业包。安装时事件定义、指标、漏斗、看板一起建好。
数据埋点方案是什么？
一份大家共用的清单：产品上报哪些事件、每个事件带哪些属性、什么类型、从哪一端报。它是「提问题的人」和「写埋点代码的人」之间的约定，见埋点方案。
有没有 Excel 版的埋点文档模板？
有。这里导出的事件表和属性表就是 CSV，Excel、WPS、飞书表格、腾讯文档都能直接打开。Excel 打开中文乱码时，勾上「CSV 加 BOM」再下载。
一个产品应该埋多少个事件？
能回答你的问题就够。这里的模板每个 9–14 个事件，其中 2–6 个是必需。真有问题要回答时再加，不要「先埋上以防万一」。
事件从前端报还是从服务端报？
屏幕上的行为（浏览、点击、加购）用网页或 App SDK 报；钱和状态变化（支付、退款、续费）从服务端报，挡不掉，也能去重。
这个工具会帮我起事件名吗？
不会。它只按 TapCub 事件目录的规则检查你写的事件名格式。模板里的事件名本身就是一套统一的写法，可以照着来。
方案写好了怎么变成代码？
点「生成埋点代码」，埋点代码生成器会带着你的事件和属性打开，给出 GA4 dataLayer / GTM 步骤，或 TapCub 网页、小程序、App、服务端 SDK 的调用。
接入 TapCub 之前必须先写埋点方案吗？
不必。装上脚本就有浏览、来源和点击数据，行业模板也可以之后再装。多个团队各自手写埋点时，方案的作用才最大。
我输入的内容会上传吗？
不会。模板数据已经在页面里，所有内容都在你的浏览器里生成。