useExposure()

useExposure 是通用的「元素進視口一次性曝光」時機偵測：對目標元素掛 IntersectionObserver（預設可見比例 ≥ 0.5），元素首次進入視口時呼叫一次回呼並自動停止監測（每元素只觸發一次）。

它只負責時機，回呼內做什麼完全由你決定——呼叫 useTracker 上報 WebSDK、呼叫業務自有打點 SDK、或純 UI 邏輯（懶載入 / 動畫觸發）都可以。framework 內部的廣告曝光（useAdTrack）與 SwLink 的 :track.exposure 都基於它。

SSR / 無 IntersectionObserver 環境自動 no-op（回傳空 cleanup），客戶端安全。

參數

useExposure(el, onExposed, options?)

回傳值

() => void —— cleanup 函式：手動停止監測（元件卸載時呼叫；已觸發過則為冪等 no-op）。

使用範例

// 範例 1：內容卡片曝光上報（搭配 useTracker）
const cardRef = ref<HTMLElement>()
let stop = () => {}
onMounted(() => {
  stop = useExposure(cardRef.value!, () => {
    useTracker().track('appPageitemExposure', { item_id: '123', item_type: 'video', /* … */ })
  })
})
onBeforeUnmount(() => stop())

// 範例 2：業務自有打點 SDK（逃生艙 —— 回呼內隨意）
onMounted(() => {
  useExposure(bannerRef.value!, () => myOwnSdk.report('banner_seen'))
})

// 範例 3：自訂閾值（長卡片露出 20% 即算曝光）
onMounted(() => {
  useExposure(listItemRef.value!, onSeen, { threshold: 0.2 })
})

注意事項

• 每元素只觸發一次：觸發後內部自動 disconnect，列表複用 DOM（虛擬滾動）時如需重新計曝光，須重新呼叫。
• 內容卡片優先用 SwLink :track：卡片連結場景 SwLink 已內建曝光 + 點擊雙埋點（內部即本 composable），不必手動接。
• 在 onMounted 內呼叫（需要真實 DOM 元素）；卸載時呼叫回傳的 cleanup。

相關

• SwLink —— :track.exposure 內建曝光埋點
• useAdTrack —— 廣告曝光（內部複用本 composable）
• useTracker —— WebSDK 統一上報入口