- 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: 'ffd-web',
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
上線前確認取樣率與上報位址,避免把測試流量寫入生產報表。
