invertase · mikehardy · Sep 4, 2026 · Sep 4, 2026 · Sep 4, 2026 · Sep 4, 2026
diff --git a/.spellcheck.dict.txt b/.spellcheck.dict.txt
@@ -101,6 +101,10 @@ preflight
 preloaded
 preloader
 preloader's
+preloader.
+Preload
+pre-flight
+preflight
 programmatically
 provenance
 PRs
@@ -192,6 +196,24 @@ NativeAdView
 NativeAsset
 NativeMediaView
 PaidEvent
+PaidResponseInfo
+ResponseInfo
+adapterResponses
+loadedAdapterResponse
+valueMicros
+latencyMillis
+currencyCode
+waterfall
+waterfalls
+allowlisted
+ILRD
+nullable
+enablement
+responseInfo
+AdError
+UseFullScreenAdStatus
+autoLoad
+earnedReward
 preload
 Programmatically
 RequestOptions
@@ -226,3 +248,32 @@ onAdsExhausted
 adsExhausted
 V2
 TTL
+AdPools
+AdPoolPresets
+AdPoolProvider
+usePooledAd
+useAdPool
+useMultiFormatAd
+MultiFormatAdRequest
+MultiFormatAdPresets
+MultiFormatBannerAdView
+getAdCapabilities
+displayPreload
+maxManagedPoolAds
+degradeReasons
+bufferSize
+poolId
+emulated
+PooledAd
+refill
+refills
+poll
+stringly
+applovin
+fail-to-show
+fail-to-present
+SHOW_FAILED
+v16
+v18
+npm
+AdMob-only
diff --git a/docs.json b/docs.json
@@ -20,6 +20,9 @@
         ["European User Consent", "/european-user-consent"],
         ["Ad Inspector", "/ad-inspector"],
         ["Impression-level ad revenue", "/impression-level-ad-revenue"],
+        ["Revenue telemetry and auction diagnostics", "/revenue-telemetry-and-auction-diagnostics"],
+        ["Preload pools and multi-format recipes", "/preload-pools-and-multiformat-recipes"],
+        ["v17 API reference", "/rngma-v17-api-reference"],
         ["Video ad volume control", "/video-ad_volume-control"],
         ["Testing", "/testing"]
       ]
@@ -29,7 +32,8 @@
       [
         ["Migrating to v5", "/migrating-to-v5"],
         ["Migrating to v6", "/migrating-to-v6"],
-        ["Migrating to v15", "/migrating-to-v15"]
+        ["Migrating to v15", "/migrating-to-v15"],
+        ["Migrating to v17", "/migrating-to-v17"]
       ]
     ]
   ]

diff --git a/docs/ad-inspector.mdx b/docs/ad-inspector.mdx
@@ -22,6 +22,10 @@ Using ad inspector, you can:
 
 To see more information about ad inspector, see the [official documentation](https://developers.google.com/admob/android/ad-inspector).
 
+For programmatic `ResponseInfo` / paid telemetry from the React Native API (waterfall
+rows, compact paid snapshots, distinct no-fill), see
+[Revenue telemetry and auction diagnostics](/revenue-telemetry-and-auction-diagnostics).
+
 ## Launch ad inspector
 
 Ad inspector can be launched from anywhere in your app. There are three different ways to launch ad inspector.

diff --git a/docs/common-reasons-for-ads-not-showing.mdx b/docs/common-reasons-for-ads-not-showing.mdx
@@ -108,3 +108,5 @@ Some private DNS providers can block ads from displaying. If your device or emul
 
 - Mobile Ads SDK [iOS](https://developers.google.com/admob/ios/quick-start), [Android](https://developers.google.com/admob/android/quick-start)
 - [Common reasons for ads not showing](https://support.google.com/admob/answer/9469204)
+- [Migrating to v17](/migrating-to-v17) — structured errors, no-fill vs failure, diagnostics
+- [Revenue telemetry and auction diagnostics](/revenue-telemetry-and-auction-diagnostics) — `ResponseInfo` after load
diff --git a/docs/displaying-ads-hook.mdx b/docs/displaying-ads-hook.mdx
@@ -92,4 +92,13 @@ Return values of the hook are:
 | show         | Function                 | Show the loaded advert.                                                             |
 | destroy      | Function                 | Destroy the current ad instance.                                                    |
 
+`responseInfo` and `revenue` together cover load-time auction metadata and paid
+telemetry. See [Revenue telemetry and auction diagnostics](/revenue-telemetry-and-auction-diagnostics).
+
+To warm fullscreen inventory and poll at show time (instead of a one-shot hook), see
+[Preload pools and multi-format recipes](/preload-pools-and-multiformat-recipes).
+
+Upgrading from v16? See [Migrating to v17](/migrating-to-v17) for structured errors,
+`destroy()` ownership, and the positional-hook deprecation.
+
 [Impression-level ad revenue]: /impression-level-ad-revenue
diff --git a/docs/displaying-ads.mdx b/docs/displaying-ads.mdx
@@ -65,6 +65,11 @@ Interstitials are full-screen ads that cover the interface of an app until close
 programmatically loaded and then shown at a suitable point during your application flow (e.g. after a level on a gaming
 app has been completed, or game over). The ads can be preloaded in the background to ensure they're ready to go when needed.
 
+To keep a **buffer** of ready interstitials and poll at show time, see
+[Preload pools and multi-format recipes](/preload-pools-and-multiformat-recipes).
+For `destroy()`, structured errors, and other v17 deltas, see
+[Migrating to v17](/migrating-to-v17).
+
 To create a new interstitial, call the `createForAdRequest` method from the `InterstitialAd` class. The first argument
 of the method is the "Ad Unit ID". For testing, we can use a Test ID, however for production the ID from the
 Google AdMob dashboard under "Ad units" should be used:

diff --git a/docs/impression-level-ad-revenue.mdx b/docs/impression-level-ad-revenue.mdx
@@ -37,9 +37,14 @@ type PaidEvent = {
 
 `currency` is the public name (native Google Mobile Ads APIs expose `currencyCode`).
 Prefer `valueMicros` when present (null when exact micros are unavailable); do not
-derive micros from floating-point `value` in JS. See the [v17 API
-reference](./rngma-v17-api-reference.md#7-response-metadata-and-paid-events) for
-`ResponseInfo` / `PaidResponseInfo` shapes and load-error attachment.
+derive micros from floating-point `value` in JavaScript.
+
+`responseInfo` on a paid event is a **compact** snapshot (`PaidResponseInfo`): winning
+source and allowlisted extras only — not the full `adapterResponses` waterfall. For
+load-time auction diagnostics, distinct no-fill handling, and waterfall debugging, see
+[Revenue telemetry and auction diagnostics](/revenue-telemetry-and-auction-diagnostics).
+Canonical TypeScript shapes live in the [v17 API
+reference](./rngma-v17-api-reference.md#7-response-metadata-and-paid-events).
 
 where `RevenuePrecisions` is an enum with keys `ESTIMATED`, `PRECISE`,
 `PUBLISHER_PROVIDED`, and `UNKNOWN`. It can be imported from the library as

diff --git a/docs/mediation.mdx b/docs/mediation.mdx
@@ -18,6 +18,10 @@ To configure mediation in the AdMob UI, complete the following steps:
 For the Google Mobile Ads SDK to communicate with third-party ad networks, you need to include a mediation adapter for each network in your app. Each
 adapter must be integrated in the Android and iOS layer of your application.
 
+Some third-party networks also ship as scoped npm packages under
+`@react-native-google-mobile-ads/<network>` (optional; install only what you mediate).
+See [Migrating to v17](/migrating-to-v17#optional-scoped-mediation-adapter-packages).
+
 To choose the adapters you want to install, see Integrate open source and versioned adapters
 ([Android](https://developers.google.com/admob/android/choose-networks#integrate_open-source_and_versioned_adapters) | [iOS](https://developers.google.com/admob/ios/choose-networks#integrate_open-source_and_versioned_adapters)).