@reglow/track · v0.1

數據埋點,從第一行程式碼開始

範本已接入 @reglow/track:零執行時期依賴,自動採集頁面瀏覽、點擊、曝光與捲動深度,同時支援搜尋、收藏、評分等業務事件。上報鏈路可替換為你自己的採集服務。

零執行時期依賴SSR 安全隱私友善批次上報

安裝

npm install @reglow/track

透過 app/plugins/track.client.ts 初始化,僅在客戶端執行。

範例接收端位於 server/api/v1/analytics/collect.post.ts。

生產環境請把 serverUrl 指向真實採集服務。

  1. 01

    採集

    自動監聽 + 顯式呼叫 track(),產生標準事件體。

  2. 02

    排隊與重試

    批次入隊,失敗按指數退避重試,離線時保留。

  3. 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% 且持續 ≥ 500mselem_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 請求。

event log最近 4 筆

尚無事件,點擊左側按鈕開始。

04 / integrate

接入方式

範本已完成初始化;新建專案時依下面三步接入即可。

app/plugins/track.client.ts
// 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))
})
app/pages/example.vue
<!-- 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

    上線前確認取樣率與上報位址,避免把測試流量寫入生產報表。