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）。

相关