事件埋点使用指南
UStat 提供灵活高效的 代码埋点方式，用于记录用户在网页中的点击行为，如按钮点击、表单提交、链接跳转等操作，帮助您深入了解用户行为、优化页面设计与产品转化路径。
一、事件埋点是什么？
事件埋点是通过在网页中为特定元素添加 data-ustat="事件名称" 属性，使 UStat 能够识别用户的操作并记录为事件数据。
二、事件如何埋点？
您只需在希望被追踪的 HTML 元素（或其不超过 3 层以内的父元素）上添加以下属性：
示例代码：
点击此链接时，UStat 将记录一次名为 "BannerClick" 的事件。
三、埋点生效机制（点击层级说明）
当用户点击某个页面元素时，系统将从该元素向上最多追溯 3 层父节点，判断是否存在带有 data-ustat 属性的节点：
| 触发逻辑 | 说明 |
|---|---|
| 最多查找 3 层 | 从被点击元素向上依次检查其父级，最多查找至第三层 |
| 首次命中即触发 | 一旦遇到包含 data-ustat="xxx" 的节点，即记录为该事件，不再继续查找 |
| 未命中不触发 | 超出 3 层仍未发现埋点标记，则该点击行为不会被记录 |
✅ 正确示例：data-ustat 在可识别层级中
示例 1：点击元素本身含有埋点
点击 button 时立即上报事件名 SubmitForm。
示例 2：data-ustat 在点击元素的第 2 层父元素内
当用户点击 <p> 或 <div class="content">，由于 data-ustat 在第 2 层父元素 <div class="card">，事件 可以被正确识别，上报为 CardClick。
❌ 错误示例：超出追踪层级或未配置 data-ustat
示例 1：data-ustat 设置在第 4 层父元素（追踪失败）
点击 <span> 时，从 <span> 向上查找：
-
layer1→ ❌ 无 data-ustat -
layer2→ ❌ -
layer3→ ❌ -
layer4→ ✅ 但已超出最多3层限制
👉 此事件将无法被 UStat 捕捉到。
示例 2：结构正确但未添加 data-ustat
即使结构在 3 层内，如果没有任何元素设置 data-ustat 属性，点击也不会被追踪。
四、事件数据查看方式
成功部署代码后，您可在 UStat 平台 - 事件分析模块 中查看相关数据。
-
登录平台，进入「事件分析」模块；
-
默认展示近一天的事件总次数及趋势图；
-
可在事件列表中点击「明细」，进一步查看该事件的终端、系统、地域等详细信息。
五、使用建议
-
✅ 事件名称建议使用规范化命名，如：
BtnSubmit、NavLoginClick等； -
✅ 埋点代码应在网页最终输出的 HTML 源码中，确保被浏览器正常渲染；
-
⚠️ 避免将埋点写入延迟加载组件或异步 DOM（如 Vue/React 未渲染前）；
-
⚠️ 若页面存在缓存机制、CDN 或 JS 混淆，建议上线后进行一次检测；
-
⚠️ 埋点元素请勿使用 display:none 隐藏，否则可能无法正确触发；
-
⚠️ 每个页面可埋设多个事件，但应避免重复名称，避免数据冲突。
六、常见问题 FAQ
| 问题 | 解答 |
|---|---|
| 埋点后数据不出现怎么办？ | 请确认事件名称是否一致、埋点位置是否在 3 层内、JS 是否加载成功 |
| 可以埋在 button 或 span 上吗？ | 可以，任意 HTML 标签都支持，只要最终生成 DOM 元素并可被点击 |
| 支持多个事件同名吗？ | 可以同名，但建议避免在同一页面内重复命名不同点击源 |
如您在事件埋点过程中遇到任何问题，欢迎联系技术支持邮箱：service@ustat.com