SDK 安装

环境要求

• 仅新架构（New Architecture）：TurboModule + Fabric。要求 React Native ≥ 0.76，且宿主已开启 newArchEnabled。
• 框架无关：纯 RN 原生模块，不依赖 Expo 运行时；另提供可选的 Expo config plugin（仅构建期生效）。
• Android minSdk 24（Android 7.0+）。
• iOS 13.0+。

添加依赖

npm install novvy-ads-react-native
# 或
yarn add novvy-ads-react-native

iOS

cd ios && pod install

• pod install 阶段 podspec 会自动从 NovvyAI/novvy-ads-cocoapods GitHub Release 下载 NovvyAds.xcframework（当前锁定 1.2.1）并落到 SDK 根目录，宿主无需手动集成任何二进制。
• 最低部署目标 iOS 13.0。若宿主 Podfile 的 platform :ios 低于 13.0，请调至 13.0 或更高。
• 内置 XCFramework 仅提供 arm64 simulator（不含 x86_64 simulator），podspec 已通过 EXCLUDED_ARCHS 排除 x86_64 simulator。因此需要在 Apple Silicon Mac 上运行模拟器；Intel Mac 只能真机构建。

Android

autolinking 会自动接入，但有两条宿主侧硬要求，见下方两小节。

• 原生依赖 ai.novvy.android:sdk:1.2.0 从 Maven Central 拉取，请确认根 build.gradle 的 allprojects.repositories 中包含 mavenCentral()（RN 官方模板默认已有）。
• 最低 minSdkVersion 24（Android 7.0）。若宿主 android/build.gradle 的 minSdkVersion 低于 24，请提升至 24 或更高。
• compileSdkVersion 建议 34+；模块本身以 JDK 17 编译。
• 需要开启 New Architecture：在 android/gradle.properties 中设置 newArchEnabled=true（RN 0.76+ 默认已开启）。

app 模块必须加 -Xskip-metadata-version-check（否则编不出包）

在宿主 android/app/build.gradle 的 android { } 里加：

kotlinOptions {
    freeCompilerArgs += ["-Xskip-metadata-version-check"]
}

原生 SDK 由 Kotlin 2.2.20 编译，因此 kotlin-stdlib 会在整个依赖图上解析到 2.2.20； 而 React Native 0.76 把 Kotlin Gradle 插件钉在 1.9.24，1.9 的编译器只能读到 2.0.0 版本的 class 元数据。不加这个标记，宿主自己的每一个 Kotlin 文件都会编译失败，第一个就是 RN 模板为每个工程 生成的 MainApplication.kt：

e: MainApplication.kt: Class 'kotlin.Unit' was compiled with an incompatible version of Kotlin.
   The actual metadata version is 2.2.0, but the compiler version 1.9.0 can read versions up to 2.0.0.

本 SDK 的库模块自带同一个标记，但那只覆盖库自身的编译，管不到宿主的源码。 （升 Kotlin 版本不是可选项：KGP ≥ 2.1 把 KotlinTopLevelExtension 由 class 改成 interface， RN 0.76 的 Gradle 插件加载不了。）

MainActivity 的 launchMode 必须是 singleTop

在 android/app/src/main/AndroidManifest.xml 里确认：

<activity android:name=".MainActivity" android:launchMode="singleTop" ... >

RN 官方模板默认给的是 singleTask，而 singleTask 会在用户回桌面、再从图标切回来时，把任务栈 清到 MainActivity 为止——连带把全屏广告的 Activity 一起清掉：广告凭空消失，且不会回调 onAdDismissed。改成 singleTop（或干脆不设 launchMode）即可。

New Architecture

本 SDK 仅支持 New Architecture（TurboModule + Fabric）。请确保：

• React Native ≥ 0.76
• 宿主已启用 newArchEnabled = true（iOS 与 Android 均需）

Expo（可选）

对于 Expo Managed / CNG（prebuild）宿主，可将本包的 config plugin 加入 app.json / app.config.*。只在构建期生效，不引入任何运行时依赖，非 Expo 宿主完全不需要它：

{
  "expo": {
    "plugins": [
      ["novvy-ads-react-native", {
        "iosDeploymentTarget": "13.0",
        "androidMinSdkVersion": 24,
        "userTrackingUsageDescription": "我们会使用相关数据向你展示更相关的广告。"
      }]
    ]
  }
}

随后执行 npx expo prebuild 生成原生工程。参数全部可选：

参数	类型	默认	作用
iosDeploymentTarget	string	"13.0"	抬升 Podfile.properties 的 ios.deploymentTarget 到不低于该值
androidMinSdkVersion	number	24	抬升 gradle.properties 的 android.minSdkVersion 到不低于该值
userTrackingUsageDescription	string	无	若提供，则向 Info.plist 注入 NSUserTrackingUsageDescription（iOS ATT 授权文案）

除上表这三个可选参数外，插件还会无条件做一件事：把 MainActivity 的 android:launchMode 改写成 singleTop（理由见 launchMode 一节）。这一条对 Expo 宿主是必要的—— 未 prebuild 时宿主没有 manifest 可改，只靠文档提醒等于没有。已经 prebuild、或使用 bare 工作流的 宿主，插件同样会在下一次 prebuild 时保证这个值。

插件用的是不抛异常的 getMainActivity：manifest 结构异常时它会跳过而不是让 prebuild 失败。 若你的工程有意要用别的 launchMode，请注意全屏广告会在「回桌面再从图标切回」时被系统清掉。

Expo 宿主同样需要开启 New Architecture（"newArchEnabled": true）。

导入

import {
  NovvyAds,
  NovvyRewardedAd,
  NovvyInterstitialAd,
  NovvyMidAd,
  NovvyEndAd,
  NovvyScrollAd,
  NovvyScrollAdView,
  NovvyPauseAd,
  NovvyPauseAdView,
  NovvyBannerAd,
  NovvyBannerAdView,
  type NovvyBannerSize,
  type NovvyPlayerAdapter,
} from 'novvy-ads-react-native';

appId / apiKey / endpoint 由 Novvy 平台方提供。

装好后继续初始化 SDK。