SwAdPreroll

廣告位四要素

• 使用場景：影片播放前貼片階段——放進 SwVideoPlayer / SwVideoFeed 的 #preroll-ad 插槽；倒數 / 跳過 / 放行由播放器階段狀態機管，本元件只管內容與埋點
• 業界形態：IAB in-stream pre-roll（AdSDK v0.0.1 暫無對應格式，ad_type 用 framework 擴充值 preroll）
• 表現形態：貼片層內單圖直出 / 多圖輪播，fit=contain 完整顯示（播放器黑底兜邊），預設帶「廣告」合規角標
• 打點事件：adImpression（掛載即報——貼片層必然全螢幕可見，不走 IntersectionObserver）/ adClick；自動內建零組態，tracker gate 關閉靜默 no-op

選錯場景 = 埋點 ad_type / 時機全錯。按場景選元件見 廣告元件選型。

SwAdPreroll 是影片前貼片廣告元件。與 SwAdBanner 同為圖片類自渲染元件（單條直出、多條 SwCarousel 輪播），差異在貼片語境：曝光在掛載時直接上報（貼片層由播放器門控掛載 = 必然可見），圖片預設 contain 鋪滿貼片層。

文案 + CTA overlay（opt-in）：item 帶 title / description / cta / advertiser 任一時，自動在創意圖上疊加「標題 + 副文案 + CTA 按鈕」浮層（像真廣告）；只給 image 則保持純圖、不變。CTA 是按鈕樣的 <span>（整張廣告已是連結，點擊落 link）。

標準用法（配合播放器貼片階段）

<script setup lang="ts">
const { data: r } = await useFetch('/movie/detail/1')
// 舊後端 play_ads 協定（{ id, name, content, link }）一行歸一
const items = computed(() => playAdsToSwAdItems(r.value?.play_ads))
</script>

<template>
  <SwVideoPlayer
    :links="r.play_links"
    :preroll-ad="items.length > 0"
    :preroll-ad-duration="+r.play_ads_time"
    :preroll-ad-auto-close="r.play_ads_auto_jump === 'y'"
  >
    <template #preroll-ad="{ skip }">
      <!-- @empty：廣告資料異常時直接放行進正片，不讓使用者乾等倒數 -->
      <SwAdPreroll :items="items" slot-key="player_preroll" page-key="movie" @empty="skip()" />
    </template>
  </SwVideoPlayer>
</template>

system/info 的 ads.app_info_player_preroll 槽位與 play_ads 同形，同樣用 playAdsToSwAdItems() 歸一。

Props

Events

playAdsToSwAdItems

舊後端 play_ads 協定歸一函式（auto-import）：

playAdsToSwAdItems(playAds: PlayAdProtocolItem[] | null | undefined): SwAdItem[]
// 映射：id→id(String) / name→name / content(圖)→image / link→link
// null / undefined / 非陣列 → []（配合 @empty 收口）

創意浮層 Token（--sw-ad-overlay-*）

廣告創意上的標題 / 描述 / CTA 浮層由內部 AdOverlay 算繪，SwAdPopup / SwAdSplash 與本元件共用同一套旋鈕：

注意事項

• 曝光時機與其它 SwAd* 不同：banner 等用 IntersectionObserver 進視口才報；本元件掛載即報——別把它放在貼片層以外的常規版面（會在不可見時誤報曝光），常規版面用 SwAdBanner。
• 倒數 / 跳過按鈕 / 自動放行都是播放器貼片階段的職責（prerollAdDuration / prerollAdAutoClose / slot 作用域 skip()），本元件不重複實作。
• 影片流貼片（貼片內容是影片而非圖片）為 v2 預留，等真實需求。

相關

• SwVideoPlayer 前貼片階段
• 廣告底座與打點 · 廣告元件選型