useTracker()

useTracker 是埋點統一上報入口——按 system/info.tracker 設定自動分流到集團 WebSDK 或自建通道（#228），業務側無感。業務 / 元件呼叫 useTracker().track(event, payload) 上報自訂事件，不直接碰 window.WebSDK —— 繞過它會丟掉 framework 的 gate（設定未就緒自動 no-op）+ 降級（懶載入 / 容錯），裸呼在設定缺失時會報錯。

工作原理

  1. 雙重 gate —— 滿足以下兩條才真正上報，缺任一 → 靜默 no-op（不報錯）：
    • ModuleOptions.tracker.enabled 為真（總開關，預設 true）
    • system/info.tracker 任一通道設定就緒：endpoint（自建通道，#228）或 appId + encryptedConfig（集團 WebSDK 通道）——兩通道行為與優先級見打點底座 · 兩種上報通道

    這讓「後端設定未就緒」場景零特殊處理：元件埋點照寫，執行時自動不發，後端給設定後自動開始上報。
  2. 懶載入 + 容錯 —— WebSDK 通道下首次上報觸發 SDK 懶載入；SDK 未就緒 / 單事件失敗均吞掉（console.error），不打斷業務（fire-and-forget）。自建通道則完全不載入 WebSDK——事件入記憶體佇列批量 flush（sendBeacon 優先、fetch keepalive 兜底），細節見打點底座 · 兩種上報通道。

回傳值

名稱類型說明
isEnabled() => booleantracker 是否已啟用（總開關 + 後端設定都就緒）
track(event: WebSdkEvent | (string & {}), payload?: Record<string, unknown>) => void上報一個事件（fire-and-forget，未啟用時靜默 no-op）

event：預置枚舉 + 自訂事件名（雙通道語義不同）

event 接受 WebSdkEvent 預置枚舉（保留 IDE 補全）或任意自訂字串，兩條上報通道對枚舉外名字的行為不同：

  • 自建通道（system/info.tracker.endpoint）：自訂事件名透傳入庫（後端自由建表）——業務事件如 login / sign_up / favorite / like 直接上報即可。命名規範 snake_case、不與預置枚舉同義重複。
  • 集團 WebSDK 通道：SDK 只認下表 28 個枚舉，枚舉外名 dev 期 console.warn 後忽略（prod 靜默）——白名單是 SDK 的約束。

SDK 實際支援的 28 個預置事件：

分類事件
頁面 / 導航navigation、appPageView、appInstall、pageClick、appPageitemExposure、appPageitemClick
推薦recommendListView、recommendListClick
內容videoEvent、novelEvent、comicEvent
搜尋keywordSearch、keywordClick
廣告（自渲染）advertising、adImpression、adClick
廣告（AdSDK 聯動）adRequest、adFill、adNoFill、adLoadSuccess、adImpressionSdk、adClickSdk、adClose、adError
IMimEvent、imConversationView、imConnectionSuccess、imMessageContent

payload 欄位各異、由 SDK 內部按事件 schema 校驗，framework 不逐事件細化類型（統一 Record<string, unknown>）。

使用範例

// 範例 1：上報頁面瀏覽
const { track } = useTracker()
track('appPageView', { page_key: 'home', page_name: '首頁' })

// 範例 2：上報搜尋關鍵字
function onSearch(keyword: string) {
  track('keywordSearch', { keyword })
}

// 範例 3：先判斷是否啟用再做有成本的埋點準備
const { isEnabled, track } = useTracker()
if (isEnabled()) {
  const payload = buildExpensivePayload()
  track('videoEvent', payload)
}

注意事項

  • 不要直接呼叫 window.WebSDK —— 繞過 gate / 降級，設定缺失時會拋錯。統一走 useTracker().track()。
  • 廣告埋點不要手拼欄位 —— 走 useAdTrack（位級 + 創意級欄位自動組裝），或直接用 SwAd* 元件（內建曝光 / 點擊埋點）。
  • 上報是 fire-and-forget，不回傳 Promise；失敗只 console.error，不影響業務流程。

相關