主题
Novvy Ads Flutter Plugin
Flutter 端广告插件对接文档。当前版本 1.2.1。
从 1.1 升级
1.2 兼容 1.1：无需修改任何代码，把依赖版本号换成 ^1.2.1 即可。插件版本号独立递增（任一端原生升级都会带动插件发新版）：当前 1.2.1 封装 iOS 原生 1.2.1 与 Android 原生 1.2.0，详见SDK 安装。
本插件是原生 Novvy Ads SDK（Android / iOS）的薄封装层：仅暴露 SDK 顶层入口（初始化 + 用户/内容上下文），广告本身通过各自的类创建和驱动。
接入顺序
SDK 安装（pubspec 依赖）
↓
初始化 SDK（appId / endpoint / apiKey）
↓
设置用户与内容上下文 // 短剧场景是填充前提
↓
按广告类型接入（load → show / 嵌入组件）- SDK 安装 —— 环境要求、
pubspec.yaml依赖 - 初始化 SDK ——
NovvyAds.initialize()参数与时机 - 用户与内容上下文 ——
NovvyUserContext/NovvyContentContext - 广告类型 —— 见下表
- 错误类型 ——
onAdFailedToLoad的错误字符串取值
NovvyAds 顶层入口
NovvyAds 是一个只含静态方法的入口类，负责初始化与上下文管理。
| 方法 | 说明 |
|---|---|
NovvyAds.initialize({required String appId, required String endpoint, required String apiKey, NovvyUserContext? userContext, void Function(bool)? onComplete}) | 初始化 SDK，创建广告前必须调用。回调式，见初始化 SDK |
NovvyAds.setUserContext(NovvyUserContext profile) | 替换整个用户画像（null 字段清空原值） |
NovvyAds.updateUserContext(NovvyUserContext partial) | 按字段合并用户画像（null 字段保持原值） |
NovvyAds.setContentContext(NovvyContentContext context) | 替换整个内容上下文（null 字段清空原值） |
NovvyAds.updateContentContext(NovvyContentContext partial) | 按字段合并内容上下文（null 字段保持原值） |
详见用户与内容上下文。
广告类型一览
所有广告类继承自 NovvyAd，实例由宿主持有：保持引用直到广告结束（onAdDismissed / onAdHidden），随后调用 destroy()。
除暂停卡与横幅外，均为两段式 —— 先 load() 预加载，就绪（onAdLoaded）后再展示 / 挂载。暂停卡与横幅没有 load()：嵌入组件即发起请求。
| 广告类型 | 类 | 形态 | 展示方式 | 生命周期回调 |
|---|---|---|---|---|
| 激励视频 | NovvyRewardedAd | 全屏 | show() | onAdShowed → onUserEarnedReward → onAdDismissed |
| 插屏 | NovvyInterstitialAd | 全屏 | show() | onAdShowed → onAdDismissed |
| 信息流滑动位 | NovvyScrollAd | 内联（信息流滑动位） | NovvyScrollAdView 组件 | onAdShowed / onAdHidden / onAdPlaybackTick |
| 中插 | NovvyMidAd | 全屏（中插） | show() | onAdShowed → onAdDismissed |
| 片尾 | NovvyEndAd | 全屏（片尾） | show() | onAdShowed → onAdDismissed |
| 暂停卡 | NovvyPauseAd | 内联（暂停卡，260×90） | NovvyPauseAdView 组件 | onAdShowed / onAdHidden（实时，无预加载） |
| 叙事植入 | NovvyInsertAd | 播放器视图内铺满（叙事植入） | NovvyInsertAdView 组件，SDK 自动到点展示 | onAdLoaded / onAdShowed / onAdClosed（串行多支）→ onChainFinished |
| 横幅 | NovvyBannerAd | 内联（横幅常驻位，5 档尺寸） | NovvyBannerAdView 组件，嵌入即请求、自动轮播 | onAdLoaded / onAdShowed / onAdClicked / onAdHidden（每轮轮播各触发一次） |
短剧场景务必先设置内容上下文
短剧后端需要「当前在看哪部剧、第几集」才有填充，否则无填充。请在每次 load() / 挂载之前调用 NovvyAds.setContentContext(...)，详见用户与内容上下文。
NovvyAd 基类
| 成员 | 类型 | 说明 |
|---|---|---|
adUnitId | String | 广告位标识（构造时传入） |
adObjectId | String | 该广告实例的唯一 ID（内部生成） |
isReady | bool | 是否已加载就绪 |
onAdLoaded | void Function()? | 加载成功回调 |
onAdFailedToLoad | void Function(String error)? | 加载/请求失败回调，error 为错误描述字符串 |
load() | Future<void> | 预加载。回调驱动：结果通过 onAdLoaded / onAdFailedToLoad 送达，不通过返回的 Future（可安全 fire-and-forget）。暂停卡不使用 |
destroy() | Future<void> | 释放资源，幂等 |
错误处理
与 Android SDK 的密封类 NovvyError 不同，Flutter 侧 onAdFailedToLoad 直接回传 String 错误描述（无填充也走此回调）。可能的取值见错误类型。
回调与曝光
每种广告通过在实例上赋值回调闭包接收事件。回调统一在主 isolate（UI 线程） 触发，各类型的回调表见对应广告类型页。
点击、曝光、跳转等追踪与计费由原生 SDK 内部自动处理，宿主无需干预。点击同样如此 —— 唯一例外是横幅：它在 SDK 处理完点击之后再调 onAdClicked，供宿主自己埋点。