novvy-ads-react-native-admob
v1.2.2-stable.0
Published
AdMob mediation adapter for the Novvy Ads React Native SDK — lets an existing AdMob waterfall call Novvy as a custom event. No JavaScript API: installing the package is the whole integration.
Maintainers
Readme
novvy-ads-react-native-admob
AdMob mediation for the Novvy Ads React Native SDK. Lets a publisher's existing AdMob waterfall call Novvy as a custom event.
No JavaScript API. Android and iOS.
What this package does
Nothing at runtime. It carries the native Novvy AdMob adapter into your app's
build — which is the only way an npm package can do that without you editing
android/ and ios/ yourself.
A mediated ad never crosses the TurboModule boundary:
JS: react-native-google-mobile-ads (BannerAd / InterstitialAd / RewardedAd)
→ native AdMob SDK → waterfall
→ reflectively loads NovvyAdMobMediationAdapter
→ NovvySDKInstall
npm install novvy-ads-react-native-admobThree packages have to be present, and npm will install the two peers for you if they are not already there:
{
"dependencies": {
"novvy-ads-react-native": "1.2.2", // exact — see Versioning
"react-native-google-mobile-ads": "^16.0.3", // yours; supplies the Google Mobile Ads SDK
"novvy-ads-react-native-admob": "1.2.2-stable.0" // this package
}
}Then cd ios && pod install. There is nothing to import and no
react-native.config.js to write — autolinking finds both halves on its own.
Adding the dependency is the integration.
react-native-google-mobile-adsmust be>=15.0.0 <16.1.0. See Requirements; a 16.1+ host fails atpod install.
iOS pod install needs network access
The adapter's Swift sources are not in the npm tarball. The podspec's
prepare_command downloads them from a tag in
novvy-ads-cocoapods on every
pod install, verifies they landed, and refuses to install if they did not.
This is not an extra requirement so much as an existing one restated:
novvy-ads-react-native's own podspec fetches NovvyAds.xcframework the same
way, so a machine that cannot reach GitHub cannot install the Novvy iOS SDK at
all, with or without this package. Shipping a second copy of the sources in the
tarball would not change that, and it would make the published tarball depend on
whatever happened to be sitting in the publisher's working directory.
Two things you must still do
1. Initialize Novvy before any AdMob ad is requested
import { NovvyAds } from 'novvy-ads-react-native';
await NovvyAds.initialize({
appId: 'YOUR_APP_ID',
endpoint: 'https://bid.novvy.ai',
apiKey: 'YOUR_API_KEY',
});The adapter cannot initialize the SDK — an app id, endpoint or api key mistyped into a dashboard field would be a silent no-fill with no diagnostic anywhere, so those values are deliberately not dashboard fields. Every load re-checks initialization instead and reports a no-fill while it is missing.
Calling this once at app start, as you would for direct integration, is sufficient; it does not need to be tied to AdMob's lifecycle.
2. Configure the custom event in the AdMob dashboard
One entry per platform, because the class name is not the same on both:
| Platform | Class Name |
| --- | --- |
| Android | ai.novvy.android.mediation.admob.NovvyAdMobMediationAdapter |
| iOS | NovvyAdMobMediationAdapter |
| Field | Value |
| --- | --- |
| Parameter | {"adUnitId":"<your Novvy ad unit id>"} |
The adapter is loaded reflectively from that class-name string — on Android by
fully-qualified name, on iOS by the adapter's @objc name, which is why it is
unqualified there. Nothing else triggers it, so this step is not optional, and a
typo produces a no-fill rather than an error.
Callbacks come from react-native-google-mobile-ads
Lifecycle events for a Novvy ad shown through mediation arrive on the
react-native-google-mobile-ads listeners, not on NovvyAdEvent. That is
intended: the mediation layer owns the impression count for these ads, and a
second set of callbacks would leave you reconciling two numbers that cannot be
made to agree.
novvy-ads-react-native's own listeners continue to serve direct-integration
placements (scroll / pause / insert / banner) as usual. The two paths coexist and
do not interact.
Supported formats
Rewarded, interstitial and banner.
Banner rotation is switched off on the mediated path: AdMob's AdView re-runs
the whole waterfall on its own interval and hands the adapter a fresh instance
each time, so a second rotation underneath would swap creatives the mediation
never counted an impression for.
User and content targeting
Set through novvy-ads-react-native as usual — NovvyAds.setUserContext(...) /
NovvyAds.setContentContext(...). The values are read when a bid request is
built, so a mediated request picks up whatever is current, with no per-ad
plumbing.
One consequence worth knowing: a mediated request can be triggered by AdMob at a moment you do not control (a banner's own refresh timer, for instance). Keep the content context maintained as screen state — updated when the user enters a drama or advances an episode — rather than set immediately before a load.
Requirements
React Native 0.76+ with the New Architecture, Android
minSdk24 and iOS 13.0, matchingnovvy-ads-react-native.react-native-google-mobile-ads>=15.0.0 <16.1.0. The iOS adapter sources are written against the Google Mobile Ads SDK 12.x Swift API and the pod requires~> 12.0, which has to intersect whatreact-native-google-mobile-adsasks for. Unlike its Flutter counterpart, it asks with a bare version string, which CocoaPods reads as= x.y.z— so the intersection is a single point and the usable range is narrow:|
react-native-google-mobile-ads| Google-Mobile-Ads-SDK | | | --- | --- | --- | | 14.2.5 | 11.7.0 | no intersection | | 15.0.0 | 12.2.0 | ok — lower bound | | 15.8.3 | 12.11.0 | ok | | 16.0.3 | 12.14.0 | ok — upper bound | | 16.1.0 | 13.1.0 | no intersection | | 16.5.0 | 13.5.0 | no intersection |A 16.1+ host fails during
pod install— loud, and before a build.⚠️ Do not reach for
$RNGoogleMobileAdsSDKVersion. That Podfile global overrides the GMA versionreact-native-google-mobile-adsrequests, so a 16.1+ host can force 12.14.0 and makepod installsucceed. It then breaksreact-native-google-mobile-ads's own iOS code, which is compiled against the GMA 13 API — compile errors if you are lucky, a build that links and is missing symbols at runtime if you are not. Supporting GMA 13 means new adapter sources upstream, not a wider range here.Android is unconstrained: the adapter takes
play-services-adsascompileOnlyso the host keeps ownership of that version, which is why this package declares no Gradle dependency on it.Android: your app module needs
freeCompilerArgs += ["-Xskip-metadata-version-check"], exactly asnovvy-ads-react-native's README already requires — the Novvy native SDK is built with Kotlin 2.2.20 while React Native 0.76 pins the Kotlin plugin to 1.9.24. This package inherits the requirement rather than adding one; if you have already installednovvy-ads-react-native, the flag is there.iOS: nothing to configure. The pod adds
-ObjCto your app's link flags itself, and needs to — a stock React NativePodfileuses static libraries and adds no-ObjCof its own, and without it the linker is free to discard an adapter class that nothing references at compile time. (This differs from the Flutter package, where the recommendeduse_frameworks! :linkage => :staticalready supplies the flag and the podspec's copy is redundant.) If you overrideOTHER_LDFLAGSin your own build settings, keep$(inherited).Expo: no config plugin is needed — this package has nothing to write into the native projects, unlike the AdMob app id, which
react-native-google-mobile-adsalready handles. Runnpx expo prebuildand build as usual. Expo Go cannot run it; nothing native can.
Versioning
This package's version names the novvy-ads-react-native version it is built
against, plus a counter for releases against that version:
| novvy-ads-react-native | this package | rule |
| --- | --- | --- |
| 1.2.0 (release) | 1.2.0-stable.0, 1.2.0-stable.1, … | append -stable.<N> |
| 1.2.0-beta.1 (prerelease) | 1.2.0-beta.1.0, 1.2.0-beta.1.1, … | append .<N> |
This release is the first row: the core it targets, 1.2.2, is a release,
so the version is 1.2.2-stable.0. The core spent one generation as the
prerelease 1.2.0-beta.1 — where the banner placement first landed — and
reached GA at 1.2.1 with the native SDKs split onto independent version
lines; the 1.2.2 core release moved only the iOS one. At this release: iOS
NovvyAds 1.2.2, Android ai.novvy.android:sdk 1.2.0. The banner placement
both lines carry is the same one that prerelease introduced.
The two native artifacts are versioned per platform now, and at this release they do not agree with each other either:
| native line | value | where |
| --- | --- | --- |
| Android adapter | ai.novvy.android:admob-adapter:1.2.0.0 | this package's android/build.gradle |
| iOS adapter | sources from the admob-v1.2.2.0 tag of novvy-ads-cocoapods | this package's podspec |
| Android core | 1.2.0 | resolved transitively by novvy-ads-react-native |
| iOS core | 1.2.2 | vendored by novvy-ads-react-native |
The Android adapter deliberately stays on 1.2.0.0: no admob-adapter:1.2.1.0
or 1.2.2.0 exists, and one that pinned a newer sdk would drag a second
SDK instance into
the process beside the one novvy-ads-react-native initializes — a permanent
silent no-fill. See the comment on that coordinate in android/build.gradle.
novvy-ads-react-native is pinned to an exact version in
peerDependencies, not a range, and you should pin this package the same way.
Each native half is built against one specific core version — the Android AAR
pins ai.novvy.android:sdk, and the iOS sources come from a tag that pins
NovvyAds — so if a range let your app resolve a different core, you would get
either an ABI mismatch or two SDK instances, and the adapter's isInitialized
check would be looking at the one JavaScript did not initialize. The symptom is a
permanent silent no-fill.
Why stable, and why not 1.2.0-0
Because the revision has to sort after the core prereleases, and semver's ordering rules make the obvious spellings wrong.
semver §11.4.3 ranks purely numeric prerelease identifiers below
alphanumeric ones. So the most natural version, 1.2.0-0, sorts before every
beta:
1.2.0-beta.2.0 > 1.2.0-0 ← backwards
^1.2.0-0 → 1.2.0-beta.2.0 ← `npm update` moves a GA-core adapter back to a beta oneAnd a beta adapter against a GA core is exactly the mismatch above. So the revision must begin with a letter, and that letter has to put the word after every prerelease tag the core uses:
| candidate | |
| --- | --- |
| stable, rev, release | sorts after alpha / beta / rc |
| ga, final, r, dev, patch | all sort before rc |
The dividing line is rc: g, f, d and p all precede r, and a bare r
is a prefix of rc and therefore smaller. The two words that feel most natural,
ga and final, are both wrong — which is why this is not a matter of taste.
Two constraints follow, and both are frozen:
novvy-ads-react-nativeprerelease tags are limited toalpha,betaandrc.stablealso beatssnapshot, buttestorzetawould flip the order.stablecannot be changed. Any lexically smaller word would make new versions sort before old ones.
scripts/check-version.js in this package's repository enforces the
consequences on every publish. It cannot enforce the causes — see
the plan document.
Two things this buys, and two it costs
The scheme is self-describing: you can read the core version straight out of the
package version. And because every version of this package is a prerelease, a
^ range is structurally confined to one core — ^1.2.0-beta.1.0 resolves
only within 1.2.0-* and cannot reach 1.3.0-beta.1.0 or 1.3.0-stable.0,
where a plain ^1.2.0 on an ordinary package would climb to 1.3.0 without
asking. That is a stronger guarantee than peerDependencies, which reports the
conflict after the fact.
One thing that range does reach is the GA-core adapter for the same core:
^1.2.0-beta.1.0 matches 1.2.0-stable.0, because both are prereleases of
1.2.0. So npm update will carry you from a beta-core adapter to a GA-core
one, while your novvy-ads-react-native is still pinned to 1.2.0-beta.1 —
and npm will refuse the install on the peer conflict. That is the intended
outcome, not a bug: the two must be upgraded together, and this is the loud
version of finding out.
What it costs:
npm install novvy-ads-react-native-admobpicks a prerelease. Because there is no non-prerelease version to fall back on, a bare install resolves through thelatestdist-tag like any other package — but whatlatestpoints at here is always a prerelease, and a version range you write by hand will only match one if it says so.^1.2.2matches nothing at all;^1.2.2-stable.0is the form to write, and thenpm installabove produces it for you.- The counter at the end of the version is not the native adapter revision.
It counts releases of this npm package against one core, so a
documentation-only release increments it while the native artifacts stand
still. The native revision lives in the exported constants —
NOVVY_ADMOB_ADAPTER_VERSION_ANDROIDandNOVVY_ADMOB_ADAPTER_VERSION_IOS— which is the only place it can be read;NOVVY_ADS_CORE_VERSION_ANDROID/_IOSgive the core each half was compiled against. There are two of each because the native lines are per-platform now: at this release the npm version is1.2.2-stable.0while the native artifacts read1.2.0.0(Android) andadmob-v1.2.2.0(iOS) — no two of the three lines spell the same string, which is the point. All four constants are diagnostics — nothing reads them at runtime, and you never need to import this package. - Renovate and Dependabot ignore prerelease versions by default, so you will
not get automatic upgrade PRs for this package. That is the intended behaviour
— it should move when you move
novvy-ads-react-native, not on a bot's schedule — but it means "no PRs" is not evidence that the package is unmaintained.
License
MIT — see LICENSE.
