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，不影响业务流程。

相关