useAdTrack()

useAdTrack 是廣告埋點封裝。各 SwAd* 元件用它自動上報曝光 / 點擊，業務零代碼。需要自己做廣告位渲染時也可直接用 —— 它把「位級欄位（slotKey / page，來自元件 prop）+ 創意級欄位（id / creativeId / adType，來自 item 資料）」兩層自動組裝成上報 payload，不用手拼。

上報底層走 useTracker，SDK 未設定時自動 no-op。

參數

useAdTrack(options) —— options 是位級埋點欄位：

名稱類型必填預設值說明
slotKeystring✓—廣告位鍵 → 埋點 ad_slot_key
slotNamestring''廣告位名 → ad_slot_name
pageKeystring''頁面鍵 → page_key
pageNamestring''頁面名 → page_name
adTypeAdType''預設廣告類型（item.adType 優先）→ ad_type

回傳值

名稱類型說明
reportImpression(items: SwAdItem[]) => void上報一次曝光（items 為空陣列時不發）
reportClick(item: SwAdItem) => void上報一次點擊
reportClose(items: SwAdItem[], reason: 'close' | 'skip') => void上報關閉 / 跳過（adClose，payload 帶 close_reason；空陣列不發）。關閉鈕元件已內建接線（SwAdSplash / SwAdPopup / SwAdPause），貼片「跳過」按鈕歸業務 slot 渲染——在 skip handler 裡自調 reportClose(items, 'skip')；倒數自然結束不報（正常完成）
observeImpression(el, getItems, onVisible?) => () => void綁定曝光偵測，回傳 cleanup 函式

observeImpression(el, getItems, onVisible?)

用 IntersectionObserver（threshold: 0.5）監聽 el 進入視口，首次進入即 reportImpression(getItems()) 並觸發可選 onVisible 回呼，隨後 disconnect（去重，只報一次）。

  • el: HTMLElement —— 要觀察的根元素
  • getItems: () => SwAdItem[] —— 取當前展示的廣告 item（延遲求值，拿到曝光瞬間的資料）
  • onVisible?: (items) => void —— 曝光後的額外回呼
  • 回傳 () => void —— cleanup（元件卸載時呼叫）。SSR / 無 IntersectionObserver 環境回傳 no-op

使用範例

// 範例 1：自訂廣告位接曝光 + 點擊埋點
const rootRef = ref<HTMLElement>()
const { reportClick, observeImpression } = useAdTrack({
  slotKey: 'home_banner',
  pageKey: 'home',
})
onMounted(() => {
  const stop = observeImpression(rootRef.value!, () => props.items)
  onUnmounted(stop)
})
function onClick(item: SwAdItem) {
  reportClick(item)
}

// 範例 2：手動上報曝光（非 IntersectionObserver 場景）
const { reportImpression } = useAdTrack({ slotKey: 'splash', adType: 'splash' })
reportImpression(visibleAds.value)

注意事項

  • 優先用 SwAd* 元件 —— 它們內建 useAdTrack + IntersectionObserver，無需自己接埋點。僅自訂廣告位才直接用本 composable。
  • 不在業務側手拼 payload —— 位級 / 創意級欄位映射由本 composable 統一組裝，手拼易漏欄位 / 欄位名錯。
  • 曝光去重：同一 el 進視口只報一次（reported 標記 + disconnect）。

相關