useAdTrack()

useAdTrack is the ad tracking wrapper. Each SwAd* component uses it to automatically report impressions / clicks with zero business code. You can also use it directly when rendering your own ad slot — it auto-assembles the two field layers ("slot-level fields slotKey / page from component props + creative-level fields id / creativeId / adType from item data") into the reporting payload, so you never hand-build it.

Reporting goes through useTracker underneath, which auto no-ops when the SDK isn't configured.

Parameters

useAdTrack(options) — options carries the slot-level tracking fields:

NameTypeRequiredDefaultDescription
slotKeystring✓—Ad slot key → tracking ad_slot_key
slotNamestring''Ad slot name → ad_slot_name
pageKeystring''Page key → page_key
pageNamestring''Page name → page_name
adTypeAdType''Default ad type (item.adType takes precedence) → ad_type

Return Value

NameTypeDescription
reportImpression(items: SwAdItem[]) => voidReport one impression (does nothing when items is empty)
reportClick(item: SwAdItem) => voidReport one click
reportClose(items: SwAdItem[], reason: 'close' | 'skip') => voidReport close / skip (adClose with close_reason in payload; no-op on empty array). Components with close buttons are pre-wired (SwAdSplash / SwAdPopup / SwAdPause); the preroll "skip" button is rendered by your slot — call reportClose(items, 'skip') in your skip handler; natural countdown completion is not reported
observeImpression(el, getItems, onVisible?) => () => voidBind impression detection; returns a cleanup function

observeImpression(el, getItems, onVisible?)

Uses IntersectionObserver (threshold: 0.5) to watch el entering the viewport. On first entry it calls reportImpression(getItems()) and the optional onVisible callback, then disconnects (dedup — reported only once).

  • el: HTMLElement — the root element to observe
  • getItems: () => SwAdItem[] — returns the currently shown ad items (lazy — captures data at impression time)
  • onVisible?: (items) => void — extra callback after impression
  • Returns () => void — cleanup (call on unmount). Returns a no-op under SSR / environments without IntersectionObserver

Usage Examples

// Example 1: wire impression + click tracking into a custom ad slot
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)
}

// Example 2: report impression manually (non-IntersectionObserver case)
const { reportImpression } = useAdTrack({ slotKey: 'splash', adType: 'splash' })
reportImpression(visibleAds.value)

Caveats

  • Prefer SwAd* components — they bundle useAdTrack + IntersectionObserver, so you don't wire tracking yourself. Use this composable directly only for custom ad slots.
  • Don't hand-assemble payloads on the business side — slot-/creative-level field mapping is centralized here; hand-building risks missing or misnaming fields.
  • Impression dedup: a given el reports only once per viewport entry (reported flag + disconnect).