广告组件选型

framework 的 SwAd* 广告组件族按广告位场景（placement）组织，与业界主流 SDK（AdMob / MAX 系的 BannerAd / InterstitialAd / NativeAd）同一套词表。本文是选型的唯一决策入口：先定场景，再选组件。

为什么按场景选，不按外观选

广告组件内置了两件业务看不见但数据侧极度在意的东西：

埋点 ad_type：每个组件按自身场景上报固定的 ad_type（banner / mrec / popup / preroll / floating…）。拿 SwAdBanner 去做弹窗，上报的 ad_type=banner 会让数据侧的弹窗报表永远是 0。
曝光时机语义：大多数组件用 IntersectionObserver"进视口一次"上报曝光；但 SwAdPopup 是"弹层展示即报"、SwAdPreroll 是"挂载即报"（贴片层由播放器门控、挂载=必然可见）。把 SwAdPreroll 放进常规版面，会在用户根本看不见时虚报曝光。

反面案例（真实业务考古，匿名化）：某仓为列表页自造了宫格广告组件——点击埋点写了、曝光埋点整段缺失，上线后数据侧只有 click 没有 impression，CTR 报表全部失真；另一仓的应用推广卡组件埋点代码整段空置（写了注释没写实现）。自造广告组件的埋点几乎必然烂尾，这正是埋点下沉到 framework 组件的原因。

场景选型表

我要做的广告位	用	业界对应词	曝光时机	典型数据源
进站 / 开屏自动弹（带频控）	SwAdSplash（`mode=sequential/carousel`）	App-Open / Splash	弹层展示即报（`ad_type=splash`）	`system/info.layers`
业务触发全屏弹窗（点击 / feed 每滑 N 条）	SwAdPopup（`ref.open()`）	Interstitial / Vignette	弹层展示即报（`ad_type=popup`）	业务自定
页面横幅（顶 / 中 / 页脚 / 播放器周边）	SwAdBanner	Banner / Leaderboard	IO 进视口一次	`ads.home_banner` 等
正文侧栏 / 播放页矩形位	SwAdMrec	MREC（IAB 300×250）	IO 进视口一次	`ads.*_mrec`
应用推荐宫格 / 横排 / 列表宫格	SwAdIcon	Icon ads	IO 进视口一次	`ads.app_info_*`
文字链（导航条下 / 顶部）	SwAdText	Text link	IO 进视口一次	`ads.top_links`
公告位横向滚动	SwAdMarquee	Marquee	IO 进视口一次	`ads.*_marquee`
内容流内原生卡	SwAdNative	Native / In-feed	IO 进视口一次	`ads.*_feed`
左右侧固定悬浮（窄屏隐藏）	SwAdFloating	Floating / Anchor	可见即报	`ads.app_float_right`
视频前贴片（播放器 `#preroll-ad` 插槽）	SwAdPreroll	IAB in-stream pre-roll	挂载即报	详情接口 `play_ads` / `ads.app_info_player_preroll`
视频暂停广告（播放器 `#pause-ad` 插槽）	SwAdPause	Pause Ad / Pause Screen Ad	展示即报（暂停 gating 通过弹，可关闭）	`ads.app_info_player_pause`
合规「广告」角标	SwAdLabel	Ad badge	不上报	—

预留场景（暂无组件，名字已占住、将来不得用别名实现）：SwAdInterstitial（插屏）。需要这些场景时提 framework issue，不要业务自造。

「广告位四要素」怎么读

每个 SwAd* 组件的 JSDoc 文件头和 docs 组件页头部都有同款四要素块：

使用场景：这个组件该出现在页面的什么位置、什么时机——对不上就换组件
业界形态：IAB / 主流 SDK 的对应词（方便与数据侧、运营对齐口径）
表现形态：渲染出来长什么样（单图 / 轮播 / 宫格 / 弹层…）
打点事件：自动上报哪些事件、曝光时机是哪种语义

写代码落到具体组件前，先核四要素的「使用场景」行；UI 长得像不代表场景对。

数据源协议速查

所有广告数据来自后端，常见三类：

// ① system/info.layers —— 进站开屏队列（SwAdSplash）
//    每层 { type: 'adv'|'app'|'notice', data: ... }

// ② system/info.ads.* —— 按槽位 key 下发的各广告位
//    如 ads.home_banner / ads.top_links / ads.app_float_right

// ③ 详情接口 play_ads —— 视频前贴片（{ id, name, content, link }）
//    一行归一：playAdsToSwAdItems(r.play_ads) → SwAdItem[]

组件统一只认 SwAdItem；将来接入 AdSDK（getAd 数据面）会提供同样归一到 SwAdItem 的 adapter，组件无感切换数据源。

埋点链路与 gate

曝光 / 点击埋点组件内置零配置，走 useAdTrack → WebSDK（adImpression / adClick）
上报受 swift.config.json 的 tracker.enabled + system/info.tracker 双重 gate——缺任一静默 no-op，组件照写、不发请求，开发期不会误报脏数据
业务额外统计用组件的 @impression / @click 事件（自动埋点已发，事件供叠加消费）
自有打点 SDK 场景：原始事件全透传 + useExposure 公开曝光时机，可完全绕开内置埋点