Ad Components & Tracking

Selection first: the decision entry for picking SwAd* by scenario (not by looks) is Ad Component Selection; the "Four Essentials" block atop each component page is the final check before coding.
The foundation lives elsewhere: generic tracking capabilities (automatic pageView / useTracker custom events / :track content tracking / useExposure) are documented in the Tracking Foundation — this page only covers the ad-slot consumer.

framework provides a set of self-rendering SwAd* components whose tracking is built on the Tracking Foundation. Business code integrates ad slots with zero code and automatic instrumentation — no need to write ad components or hand-roll IntersectionObserver.

SwAd* Components

Pick by ad slot format (naming / ad_type aligned with the group AdSDK vocabulary for easy future migration):

Component	Format	Typical use
`SwAdBanner`	Banner (single / carousel)	Content-flow banner, sidebar
`SwAdMrec`	Medium rectangle (300×250)	In-feed insert
`SwAdIcon`	Icon grid	App recommendation
`SwAdText`	Text link	Text promotion
`SwAdMarquee`	Marquee	Scrolling notice
`SwAdNative`	Native feed card	Native in-feed ad
`SwAdSplash`	Entry splash popup / story (`ad_type=splash`)	Auto-popup on entry, splash
`SwAdPopup`	Business-triggered popup / story (`ad_type=popup`)	Click / exit-intent / every N swipes in a feed
`SwAdFloating`	Side floating	PC side
`SwAdPreroll`	Video pre-roll	Player `#preroll-ad` slot
`SwAdPause`	Video pause ad (`ad_type=pause`)	Player `#pause-ad` slot (shows on pause, closable)

Usage (self-rendering + auto tracking, zero code):

<SwAdBanner :items="ads" slot-key="home_banner" />
<SwAdSplash :items="splashAds" slot-key="splash" mode="carousel" :closable-after="4000" />

items is SwAdItem[] ({ id, image, link, name, adType? }). The component renders image + link and tracks impression / click automatically. See each component's JSDoc for props (ratio / radius / showAdLabel / mode / loop, etc.).

Compliance badge showAdLabel

Every SwAd* carries the "Ad" compliance badge by default: components without an explicit showAdLabel follow the global swiftConfig.ad.showLabel (default true). Defaulting to labeled everywhere is the compliance-safe trade-off — forgetting to turn it off just looks a bit ugly, while forgetting to turn it on means unlabeled ads, a compliance risk; opt out explicitly where needed:

Sites whose creatives already carry a baked-in ad label turn it off globally in nuxt.config.ts: swiftConfig: { ad: { showLabel: false } }
When a single slot needs different behavior, an explicit component-level show-ad-label always wins (re-enable one slot after a global off, or vice versa)

See Module Options · ad for config details; custom non-standard ad slots that need a badge use SwAdLabel directly.

Ad Tracking (automatic)

SwAd* embeds useAdTrack: element enters the viewport once → adImpression, click → adClick, close button ✕ → adClose (payload carries close_reason: 'close'; SwAdSplash / SwAdPopup / SwAdPause are pre-wired — close rate is the core "ad annoyance" signal). Tracking fields (slot-level slotKey/slotName/page + creative-level ad_id/creative_id/ad_type) are assembled automatically — zero code. Components also emit @impression / @click / @close for business use. The preroll "skip" button is rendered by your slot — call useAdTrack(...).reportClose(items, 'skip') in your skip handler (natural countdown completion is not reported).

Never hand-assemble ad tracking payloads in business code — custom non-standard ad slots that need tracking should also go through useAdTrack.

Config & Degradation

Ad tracking shares the same double gate as the foundation (tracker.enabled + system/info.tracker); missing either is a silent no-op — see Tracking Foundation · Setup & Configuration.