主题
Novvy Ads iOS SDK
iOS 端广告 SDK 对接文档。当前版本 1.2.1。
从 1.1 升级
1.2 兼容 1.1：无需修改任何代码，把 Pod 引用里的版本号换成 v1.2.1 即可，详见SDK 安装。
接入顺序
SDK 安装（CocoaPods）
↓
初始化 SDK（appId / endpoint / apiKey）
↓
设置用户与内容上下文 // 短剧场景是填充前提
↓
按广告类型接入（load → show / attach）- SDK 安装 —— 环境要求、CocoaPods 依赖
- 初始化 SDK ——
NovvySDK.shared.initialize()参数与时机 - 用户与内容上下文 ——
NovvyUserContext/NovvyContentContext - 广告类型 —— 见下表
- 错误类型 ——
NovvyError各取值含义
广告类型一览
SDK 提供以下广告类。除暂停卡（实时请求）、叙事植入（SDK 自驱动）与横幅（构造即常驻、自动轮换）外，均为两段式 —— 先 load() 预加载，就绪后再展示。adUnitId 按类型区分，请使用对应列的广告位标识：
| 广告类型 | 类 | adUnitId 类型 | 形态 | 展示方法 | 生命周期回调 |
|---|---|---|---|---|---|
| 激励视频 | NovvyRewardedAd | rewarded | 全屏 | show(from:) | Shown → Reward → Closed |
| 插屏 | NovvyInterstitialAd | interstitial | 全屏 | show(from:) | Shown → Closed |
| 信息流滑动位 | NovvyScrollAd | scroll_placement | 内联（信息流滑动位） | attach(to:) | Shown / Closed |
| 中插 | NovvyMidAd | mid_placement | 全屏（中插） | show(from:) | Shown → Closed |
| 片尾 | NovvyEndAd | end_placement | 全屏（片尾） | show(from:) | Shown → Closed |
| 暂停卡 | NovvyPauseAd | pause_placement | 内联（暂停卡，260×90pt） | attach(to:player:) | Shown / Finished（实时，无预加载） |
| 叙事植入 | NovvyInsertAd | story_placement | 播放器视图内铺满（叙事植入） | 无 —— SDK 自动到点展示 | Load → Show → Close（串行多支）→ ChainFinish |
| 横幅 | NovvyBannerAd | banner | 内联（固定尺寸常驻） | 无 —— 构造即建位，load() 起自动轮换 | Load → Show → Click / Hide（每轮重复） |
短剧场景务必先设置内容上下文
短剧后端需要「当前在看哪部剧、第几集」才有填充，否则返回 .noFill。请在每次 load() / attach() 之前调用 NovvySDK.shared.setContentContext(...)，详见用户与内容上下文。
回调与曝光
每种广告类型都有各自的 Delegate 协议，必需实现的方法是 *DidLoad / *(ad, didFailToLoadWithError:)（以及 Rewarded 的 didEarnReward、Pause 的 didFailToLoadWithError）。*DidShow / *DidClose（Pause 为 *DidFinish）通过 protocol extension 提供了默认空实现，可按需重写。唯一例外是横幅的 NovvyBannerAdDelegate：五个方法全部有默认空实现，按需重写。回调统一在主线程触发，各类型的回调表见对应广告类型页。
点击、曝光、跳转等追踪与计费由 SDK 内部自动处理，宿主无需干预。上报地址全部由服务端在 adm 里预置， SDK 只替换宏后发出，不拼接也不解析 query。
*DidShow ≠ 曝光
*DidShow 是「广告已经展示出来」的宿主回调，曝光另有可见性判据—— 广告自身可见面积达标、且连续驻留一段时间才上报（跌破重新计时，不累加）。 因此曝光时刻总是晚于 *DidShow；广告一闪而过时会有 *DidShow 而没有曝光，这是预期行为。