SwAdPause

廣告位四要素
使用場景：影片暫停時彈出的可關閉廣告（CTV / 串流媒體黃金廣告位——使用者主動停下、注意力在螢幕）。渲染進 SwVideoPlayer 的 #pause-ad 插槽，slotKey 例 play_pause
業界形態：Pause Ad / Pause Screen Ad（AdSDK 格式 pause）
表現形態：置中 / 角落卡片 + 可關閉 ✕；不全螢幕死擋——暫停畫面仍部分可見，點卡片外畫面恢復播放即關
打點事件：adImpression（展示即報）/ adClick / 關閉；自動內建零組態，gate 關閉靜默 no-op
選錯場景 = 埋點 ad_type / 時機全錯。按場景選元件見廣告元件選型。

SwAdPause 是暫停廣告位元件，屬廣告底座「播放器場景」自渲染元件。觸發與門控（gating）由播放器負責——SwVideoPlayer 開 pause-ad 後，使用者暫停 → 播放器內建 gating（延遲去抖 / 過濾系統暫停 / eligibility / 與付費牆互斥）全通過 → 顯 #pause-ad 插槽。本元件只管創意 + 頻控 + 埋點：掛載即「有效暫停時機」，按 useAdFrequency 頻控決定是否展示，命中則渲染創意卡 + 曝光埋點。

⚠️ 與付費牆 #paywall 嚴格區分：付費牆 = 變現 / 不可關 / 全螢幕死擋 / 試看播完觸發；本元件 = 廣告 / 可關 / 不擋恢復 / 暫停觸發。

Props

名稱	類型	必填	預設值	說明
`items`	`SwAdItem[]`	✓	—	廣告創意（取首條；`image` 必填，可帶 `title` / `cta` / `link`）
`slotKey`	`string`	✓	—	廣告位鍵 → `ad_slot_key`
`slotName`	`string`		`undefined`	廣告位名 → `ad_slot_name`
`pageKey`	`string`		`undefined`	頁面鍵 → `page_key`
`pageName`	`string`		`undefined`	頁面名 → `page_name`
`ratio`	`string`		`'16/9'`	創意圖寬高比
`frequency`	`AdFrequencyStrategy`		`'session'`	頻控策略（`'session'` 每會話一次 / `'always'` 每次都彈 / `'Nm'`·`'Nh'`·`'Nd'` 每 N 分·時·天一次）
`frequencyKey`	`string`		`undefined`	頻控儲存鍵（預設用 `slotKey`）
`closable`	`boolean`		`true`	顯示關閉 ✕
`showAdLabel`	`boolean`		`undefined`	「廣告」合規角標；不傳時跟隨全域 `swiftConfig.ad.showLabel`（預設 `true`，暫停廣告建議保持開啟）

Events

名稱	攜帶	說明
`empty`	—	首條無 `image` 或頻控未命中（不渲染）
`impression`	`items: SwAdItem[]`	曝光（展示即報，自動埋點）
`click`	`item: SwAdItem`	點擊創意（自動埋點）
`close`	—	點 ✕ 關閉（業務接 slot 的 `close` 收起播放器覆蓋層）

用法（渲染進播放器 `#pause-ad` 插槽）

SwAdPause 不獨立使用，業務把它放進 SwVideoPlayer 的 #pause-ad 插槽；插槽作用域 { close } 用於關閉：

<SwVideoPlayer :url="videoUrl" type="m3u8" pause-ad @pause-ad="onPauseExposure">
  <template #pause-ad="{ close }">
    <SwAdPause :items="pauseAds" slot-key="play_pause" @close="close" />
  </template>
</SwVideoPlayer>

<!-- 可調項：ratio 創意寬高比；frequency 頻控（除錯用 0 = 每次暫停都彈）；
     frequency-key 顯式頻控鍵——預設取 slot-key，發版換 key 可重置老用戶頻控；
     closable=false 隱藏 ✕（只能點卡片外恢復播放收起）；
     show-ad-label 不傳時跟隨全域 ad.showLabel（預設 true，「廣告」合規角標，建議保留） -->
<SwAdPause
  :items="pauseAds"
  slot-key="play_pause"
  ratio="16/9"
  frequency="always"
  frequency-key="play-pause-v2"
  :closable="false"
  @close="close"
/>

<script setup>
const pauseAds = [
  { id: 'pa-1', image: '/ad/pause.jpg', title: '限時會員 5 折', cta: '立即開通', link: '/vip' },
]
function onPauseExposure() {
  // 播放器層「有效暫停時機」鉤子（與元件 adImpression 獨立）
}
</script>

頻控

frequency 複用 useAdFrequency：

'session'（預設）：每會話彈一次。
N（數字）：N 天彈一次。
0：每次有效暫停都彈（無頻控）。

更細的「每會話 N 次 / 分鐘級 cooldown」待真實消費者校準後再加，當前 v1 不引入（YAGNI）。

關閉與恢復

點 ✕：emit('close')，業務接插槽 close() 收起覆蓋層；影片保持暫停態（不自動恢復）。
點卡片外畫面：覆蓋層 wrapper pointer-events:none，點擊穿透到畫面恢復播放 → 播放器 video:play 自動收起暫停廣告（恢復即關）。
頻控未命中：emit('empty') 不渲染，透明覆蓋層不阻斷點擊，照常可恢復播放。

樣式訂製 Token

以下 CSS 變數可在業務端覆蓋（fallback 即預設值）：

變數	預設值	說明
`--sw-ad-pause-card-bg`	`rgb(17 17 20 / 96%)`	創意卡背景
`--sw-ad-pause-card-shadow`	`0 8px 32px rgb(0 0 0 / 45%)`	創意卡投影
`--sw-ad-pause-title-color`	`rgb(255 255 255 / 92%)`	標題文字色
`--sw-ad-pause-cta-bg`	`var(--primary)`	CTA 按鈕底色（可填品牌漸層）
`--sw-ad-pause-cta-color`	`rgb(255 255 255)`	CTA 按鈕文字色
`--sw-ad-pause-close-bg`	`rgb(0 0 0 / 45%)`	關閉鈕底色
`--sw-ad-pause-close-color`	`rgb(255 255 255)`	關閉鈕圖示色

注意事項

gating 由播放器管：延遲去抖、過濾系統暫停（拖曳 / 緩衝 / 切到背景 / 前貼片期 / 完播）、eligibility、與付費牆互斥都在 SwVideoPlayer 內建，本元件掛載即視為有效暫停時機，詳見 SwVideoPlayer · 暫停廣告。
不擋恢復控制項：創意卡置中、卡片外區域可點恢復播放——業務別把卡片做成全螢幕遮罩。
埋點內建（ad_type=pause），受 tracker 雙重 gate。
Demo 說明：本元件渲染進播放器插槽、依賴播放器暫停態觸發，獨立 Demo 無代表性；可執行 Demo 見 SwVideoPlayer 暫停廣告場景（PauseAdDemo，暫停觸發 + 恢復即關；故本頁按 docs 約定不單列 DemoBox）。