- 01
采集
自动监听 + 显式调用 track()，生成标准事件体。
- 02
排队与重试
批量入队，失败按指数退避重试，离线时保留。
- 03
上报与聚合
POST 到采集服务，服务端按事件码生成报表。
01 / capabilities
采集能力
默认开启自动采集，业务侧只需要声明元素标识；其余能力按需开启。
自动行为采集
点击、曝光与滚动深度默认可用，业务代码只需要补 data-track-id。
批量上报与重试
队列批量上报，失败按指数退避重试，离线时保留数据，恢复网络后补发。
会话与用户
默认 30 分钟无事件换新会话；登录后 identify 绑定用户，后续事件自动携带。
隐私友好
不采集输入框内容，提供 optOut / optIn，支持采样率控制自定义事件。
SSR 安全
服务端没有 window 时自动降级为内存适配器，导入与初始化都不会报错。
远程规则
支持后端下发可视化圈选规则，命中元素自动埋点，无需逐个改代码。
02 / events
事件模型
标准事件由 SDK 自动上报，业务事件通过 track / trackSearch / trackPreference 发送。
| 事件码 | 触发时机 | 关键字段 |
|---|---|---|
| $page_view | 进入页面 / 路由切换 | page_key · page_version |
| $click | 点击带 data-track-id 的元素 | elem_id · elem_type · text · x / y |
| $exposure | 元素可见 ≥ 50% 且持续 ≥ 500ms | elem_id · ratio · visible_ms |
| $scroll | 滚动深度每增加 10% | depth · depth_px · page_version |
| biz.search | 搜索提交与结果点击 | query · is_zero_result · clicked_rank · converted |
| biz.favorite | 收藏 / 点赞 / 分享 / 评分 | target_type · target_id · score |
03 / demo
在线演示
点击左侧按钮会真实调用 SDK 方法；右侧展示本次演示上报的自定义事件。
加入购物车
track(add_to_cart)
搜索结果点击
trackSearch()
收藏商品
trackPreference(favorite)
提交评分
trackPreference(rate, 5)
自动采集的 $page_view / $click / $exposure / $scroll 可在浏览器 Network 中查看 /api/v1/analytics/collect 请求。
暂无事件，点击左侧按钮开始。
04 / integrate
接入方式
模板已完成初始化；新建项目时按下面三步接入即可。
// app/plugins/track.client.ts
import { createTrack } from '@reglow/track'
export default defineNuxtPlugin((nuxtApp) => {
const tracker = createTrack({
appId: 'reglow-nuxt-starter',
autoPageView: false,
autoTrack: { click: true, exposure: true, scroll: true }
})
nuxtApp.vueApp.use(tracker)
const router = useRouter()
tracker.pageView(router.currentRoute.value.fullPath)
router.afterEach(to => tracker.pageView(to.fullPath))
})<!-- Declarative: auto click tracking reads data-track-id -->
<button data-track-id="buy_btn" data-track-type="button">
Buy now
</button>
<!-- Directive: writes data-track-* then hands off to auto tracking -->
<button v-track="{ id: 'submit_btn', type: 'button' }">
Submit order
</button>const track = useTracker()
track?.track('add_to_cart', { sku: 'RG-2026', price: 299 })
track?.trackSearch('recycled fabric', {
clickedRank: 1,
converted: false
})
track?.trackPreference('favorite', {
targetType: 'product',
targetId: 1001
})05 / guidelines
埋点规范建议
埋点是长期资产。统一命名与口径，比一次性的全量采集更重要。
- 01
elem_id 使用「模块_动作」命名，如 detail_add_cart，避免直接使用用户可见文案。
- 02
关键转化单独定义事件与属性，不要把多个业务含义塞进同一个事件。
- 03
曝光阈值按内容类型调整：列表卡片可降低，重要横幅可提高。
- 04
页面改版后 page_version 会变化，历史热点图不应与新版本混算。
- 05
上线前确认采样率与上报地址，避免把测试流量写入生产报表。