SwAdBanner

Ad Placement Four Essentials
Use case: banner slots at the page top / middle / footer / around the player (slotKey e.g. home_banner)
Industry form: Banner / Leaderboard (AdSDK formats banner / bannerLarge)
Visual form: full-width image, single image direct render / multi-image auto carousel, optional "Ad" badge
Tracking events: adImpression (once on entering the viewport via IntersectionObserver) / adClick; built-in zero-config, silent no-op when the tracker gate is off
Picking the wrong scenario = wrong ad_type / timing in tracking. See Ad Component Selection.

SwAdBanner is the banner ad slot component — an "image-type" self-rendering component of the framework ad foundation. Pass items (the creative array returned by the backend ad API) and it renders automatically, with built-in IntersectionObserver impression + click tracking (via useAdTrack) and zero business code. A single image renders directly; multiple images autoplay.

Prefer SwAd* components for ad slots — don't write your own ad component + hand-rolled tracking. See Ad & Tracking for the full family and tracking fields.

加载中...

Props

Name	Type	Required	Default	Description
`items`	`SwAdItem[]`	✓	—	Ad creative array (from the backend ad API)
`slotKey`	`string`	✓	—	Ad slot key → tracking `ad_slot_key`
`slotName`	`string`		`undefined`	Ad slot name → `ad_slot_name`
`pageKey`	`string`		`undefined`	Page key → `page_key`
`pageName`	`string`		`undefined`	Page name → `page_name`
`ratio`	`string`		`undefined`	Aspect ratio (e.g. `'640/200'`) to prevent CLS. Follows image ratio when omitted
`radius`	`number \| string`		`0`	Corner radius (number = px, string passed to SwImage as-is, e.g. `'1.125rem'`)
`showAdLabel`	`boolean`		`undefined`	"Ad" compliance badge; when not set it follows the global `swiftConfig.ad.showLabel` (default `true`), an explicit value always wins
`autoplay`	`boolean`		`true`	Autoplay when multiple images
`autoplayDelay`	`number`		`4000`	Carousel interval (ms)

items fields (id / image / title / link / ratio / adType, etc.) are defined by the SwAdItem type; see Ad & Tracking.

Events

Name	Payload	Description
`load`	—	Creative rendered
`empty`	—	`items` empty / no displayable creative
`impression`	`items: SwAdItem[]`	Slot entered viewport (tracking already reported; this event is for extra business consumption)
`click`	`item: SwAdItem`	A creative clicked (tracking already reported)
`error`	—	Render / load error

Multi-image autoplay

With multiple items it autoplays; autoplayDelay controls the interval. Pass :autoplay="false" to disable.

加载中...

<SwAdBanner
  :items="banners"
  slot-key="home_top_banner"
  page-key="home"
  ratio="640/200"
  :radius="8"
  :autoplay-delay="3000"
  show-ad-label
/>

Caveats

Don't hand-roll tracking — impression / click tracking is built in; no need to wire IntersectionObserver or call useTracker yourself.
Pass ratio to prevent CLS — placeholder via ratio while the image loads.
Reporting is gated by tracker.enabled + system/info.tracker; silently no-ops when config is missing (the component still renders).