Novvy Ads React Native SDK

React Native 端广告 SDK 对接文档。包名 novvy-ads-react-native，当前版本 1.2.1。

从 1.1 升级

1.2 兼容 1.1：无需修改任何代码，更新依赖版本即可。包版本号独立递增（任一端原生升级都会带动插件发新版）：当前 1.2.1 封装 iOS 原生 1.2.1 与 Android 原生 1.2.0，详见SDK 安装。

本 SDK 是原生 Novvy Ads SDK（Android / iOS）的薄封装层：仅暴露 SDK 顶层入口（初始化 + 用户/内容上下文），广告本身通过各自的类创建和驱动。

接入顺序

SDK 安装（npm 依赖 + 原生工程配置）
        ↓
初始化 SDK（appId / endpoint / apiKey）
        ↓
设置用户与内容上下文        // 短剧场景是填充前提
        ↓
按广告类型接入（load → show / 挂载组件）

SDK 安装 —— 环境要求、依赖、iOS / Android / Expo 配置
初始化 SDK —— NovvyAds.initialize() 参数与时机
用户与内容上下文 —— NovvyUserContext / NovvyContentContext
广告类型 —— 见下表
错误类型 —— onAdFailedToLoad 的错误字符串取值

`NovvyAds` 顶层入口

NovvyAds 是一个只含方法的入口对象，负责初始化与上下文管理。

方法	说明
`NovvyAds.initialize(options)` → `Promise<boolean>`	初始化 SDK，创建广告前必须调用。见初始化 SDK
`NovvyAds.setUserContext(ctx: NovvyUserContext)` → `void`	替换整个用户画像（`null` 字段清空原值）
`NovvyAds.updateUserContext(partial: NovvyUserContext)` → `void`	按字段合并用户画像（`null` / 缺省字段保持原值）
`NovvyAds.setContentContext(ctx: NovvyContentContext)` → `void`	替换整个内容上下文（`null` 字段清空原值）
`NovvyAds.updateContentContext(partial: NovvyContentContext)` → `void`	按字段合并内容上下文（`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`	`boolean`	是否已加载就绪（只读）
`onAdLoaded`	`(() => void) \| undefined`	加载成功回调
`onAdFailedToLoad`	`((error: string) => void) \| undefined`	加载/请求失败回调，`error` 为错误描述字符串
`load()`	`void`	预加载。回调驱动：结果通过 `onAdLoaded` / `onAdFailedToLoad` 送达。暂停卡不使用（调用会抛错）
`destroy()`	`void`	释放资源，幂等

错误处理

onAdFailedToLoad 回传 string 错误描述（无填充也走此回调）。可能的取值见错误类型。

回调与曝光

每种广告通过在实例上赋值回调函数接收事件。所有回调统一在 JS 主线程 触发（原生侧已强制主线程 marshaling），各类型的回调表见对应广告类型页。

点击、曝光、跳转等追踪与计费由原生 SDK 内部自动处理，宿主无需干预。点击同样如此 —— 唯一例外是横幅：它在 SDK 处理完点击之后再调 onAdClicked，供宿主自己埋点。

onAdShowed ≠ 曝光

onAdShowed 是「广告已经展示出来」的宿主回调，曝光另有可见性判据—— 广告自身可见面积 > 50% 且连续满足 ≥ 1 秒才上报（跌破重新计时，不累加）。因此曝光时刻总是晚于 onAdShowed；广告一闪而过时会有 onAdShowed 而没有曝光，这是预期行为。

Novvy Ads React Native SDK ​

接入顺序 ​

NovvyAds 顶层入口 ​

广告类型一览 ​

NovvyAd 基类 ​