<SYSTEM>This is the abridged developer documentation for AdMob CMP</SYSTEM>

---

# Compose Multiplatform AdMob SDK for Android and iOS

> Six AdMob formats on Android and iOS behind one Kotlin API — suspend functions, StateFlow, and UMP consent wired into initialization.

## Quick start [Section titled “Quick start”](#quick-start) The integration has two required lines: one Maven dependency in `commonMain`, and one initialization call at the root of the app that gathers consent and starts Mobile Ads in a single step. The full setup — version catalogs, the Gradle plugin, Kotlin/Native test linking, the iOS-only Info.plist keys, and the `doctorIos` check — lives in the [Quickstart guide](/start/quickstart/). shared/build.gradle.kts 
```kotlin
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("dev.avinya.ads:admob-cmp:1.1.0")
        }
    }
}
```
 
```kotlin
// commonMain — initialize once at the root
adManager.gatherConsentAndInitialize(
    AdConfig(
        androidAppId = TestAdIds.ANDROID_APP_ID,
        iosAppId = TestAdIds.IOS_APP_ID,
        testMode = true,
    )
)
```
 On iOS, the production ordering is UMP consent, then ATT tracking authorization, then initialize with `ConsentMode.InitializeOnlyIfAlreadyAllowed`. See the [iOS setup guide](/start/ios-setup/) for the two Swift Package Manager package URLs and the three `Info.plist` keys. [Continue to the full Quickstart →](/start/quickstart/) ## Capability comparison Comparison of admob-cmp against the [basic-ads](https://github.com/LexiLabs-App/basic-ads) Compose Multiplatform ads library, with the public documentation snapshot dated 31 July 2026. | Capability | AdMob CMP | basic-ads | | --------------------------------- | -------------------------------------------------------------------------- | --------------- | | Banner ads | Yes | Yes | | Interstitial ads | Yes | Yes | | Rewarded ads | Yes | Yes | | Rewarded interstitial ads | Yes | Yes | | App-open ads | Yes | Not offered | | Native ads | Yes | Not offered | | Native ad layout DSL and pooling | adLayout {} plus NativeAdPool max-size accounting | Not applicable | | UMP consent inside initialization | gatherConsentAndInitialize, three consent strategies, privacy-options form | Consent request | | iOS ATT ordering | tracking authorization between consent and initialize | Not documented | | Paid and revenue events | AdEvent.Paid with AdValue and ResponseInfo | Not documented | | Mediation adapter hooks | AdInitializationHook at three initialization points | Not documented | | Kotlin/Native test linking | Published dev.avinya.ads.admob-cmp Gradle plugin | Not addressed | | Generated API reference | Yes | Yes | | Maven Central publication | Yes | Yes | Comparison verified on 31 July 2026 from the public documentation of both projects. "Not documented" here means that basic-ads' public documentation does not describe this capability; it is a statement about documentation coverage, not a judgement on the basic-ads maintainer. basic-ads is the older and larger project in this space and was the earlier publisher of a generated API reference for a Compose Multiplatform ads library. Corrections are welcome — please [open an issue](https://github.com/Meet-Miyani/admob-compose-multiplatform/issues) on GitHub. ## Why this exists Putting ads into a Compose Multiplatform app meant leaving Compose. The Google Mobile Ads SDKs are Android and iOS libraries with callback-based APIs, so the shared module ended up holding an expect/actual seam, two sets of platform glue, and a consent flow bolted on afterwards. Samples and libraries already covered this ground, and they helped. What was still wanted was ads shaped like the rest of a Compose Multiplatform codebase: composables for the ad surfaces, suspend functions and StateFlow for the lifecycle, and consent gathered as part of initialization rather than as a step to remember. So it was built inside an app that was being written, then extracted once the shape had settled. The APIs here are the ones that had to hold up on real screens: a native ad pool with max-size accounting, retry and cache behaviour with the numbers written down, and an iOS ordering — consent, then tracking authorization, then initialize — that the library sequences for you. ## Compatibility and ordering * Kotlin 2.3.20 * Compose Multiplatform 1.11.1 * Android minSdk 26 * iOS deployment target 15.0 The Kotlin klib does not promise binary compatibility across minor versions; re-resolve the klib when you bump the SDK. ### Consent, ATT, and initialize sequence Initialization order: UMP consent, then ATT, then initializeThe required call order on iOS — gather UMP consent, request App Tracking Transparency authorisation, then initialize the ads SDK — and what Android reports instead. Initialization order: UMP consent, then ATT, then initializeCLAUDE.md invariants #5, #11[Read this diagram in words](/reference/diagrams-in-words/#init-sequence) ### Platform support matrix | Format | Android — GMA Next-Gen, API 26+ | iOS — GMA 13.x, iOS 15+ | Notes | | --------------------- | ------------------------------- | ----------------------- | ---------------------------------------------------------------------------------- | | Banner | ✔ Supported | ✔ Supported | Anchored adaptive, inline adaptive, fixed and fluid; collapsible on both platforms | | Interstitial | ✔ Supported | ✔ Supported | TTL'd FIFO cache, 1 hour | | Rewarded | ✔ Supported | ✔ Supported | RewardEarned event | | Rewarded interstitial | ✔ Supported | ✔ Supported | Same controller shape as Rewarded | | App-open | ✔ Supported | ✔ Supported | AppOpenAdCoordinator, cooldowns, blocking; cache TTL 4 hours | | Native | ✔ Supported | ✔ Supported | adLayout DSL and pooling on both; iOS renders through UIKit | | Capability | Android | iOS | Notes | | ----------------------------------------------------------------------------------------------------- | ---------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | UMP consent and privacy-options form | ✔ Supported | ✔ Supported | canRequestAds gates every request on both platforms | | App Tracking Transparency | — Not applicable | ✔ Supported | Android has no ATT: adManager.tracking always reports AdTrackingAuthorization.NotApplicable, and the AD\_ID manifest permission governs the advertising id there instead | | Mediation adapters | ✔ Supported | ✔ Supported | No adapters are bundled; add the ones you need | | Paid and revenue events | ✔ Supported | ✔ Supported | AdEvent.Paid carries AdValue and response info | | Native video events | ✖ Not available | ✔ Supported — five events | iOS emits VideoStarted, VideoPlayed, VideoPaused, VideoEnded and VideoMuted through GADVideoControllerDelegate. The Android GMA Next-Gen SDK exposes no equivalent callback surface on NativeAd, so Android emits none. This is an upstream SDK gap, not an admob-cmp omission — do not rely on native video events for cross-platform logic. | | immersiveMode, customClickGesture, publisherProvidedId, categoryExclusions, skipUninitializedAdapters | ✔ Supported | ✖ Silently ignored | Android-only request options | | customTargeting, placementId | ✔ Supported | ✔ Supported | Mapped on both platforms; placementId maps to placementID on iOS | Platform support matrix: six formats on Android and iOSCLAUDE.md invariants #11[Read this diagram in words](/reference/diagrams-in-words/#platform-matrix) ## Roadmap * Swift Package Manager dependency import Gated on four unmet upstream conditions (swiftPMDependencies); Maven-consumer propagation remains an open unknown and the project refuses to depend on an Alpha build-tool feature. * Native video events on Android Blocked on the upstream SDK. iOS exposes GADVideoControllerDelegate with five video events; no equivalent Android callback surface is available. [Full roadmap →](/project/roadmap/) * [Quickstart](/start/quickstart/) * [Installation](/start/installation/) * [Compatibility](/reference/compatibility/) * [Roadmap](/project/roadmap/) * [API reference](/api/) * [GitHub](https://github.com/Meet-Miyani/admob-compose-multiplatform) * [Apache-2.0 license](https://www.apache.org/licenses/LICENSE-2.0.txt) Built by [Meet Miyani](https://github.com/Meet-Miyani) at [Avinya](https://avinya.dev). Not affiliated with or endorsed by Google. AdMob and Google Mobile Ads are trademarks of Google LLC.

---

# What is AdMob CMP?

> AdMob CMP is a KMP AdMob library for Compose Multiplatform — six ad formats, UMP consent and mediation behind one Kotlin API on Android and iOS.

## What is AdMob CMP? [Section titled “What is AdMob CMP?”](#what-is-admob-cmp) AdMob CMP is a KMP AdMob library — a Kotlin Multiplatform wrapper over the Google Mobile Ads SDKs that ships a single Kotlin API for the formats AdMob publishers actually use, on both Android and iOS. The Android side binds the GMA Next-Gen SDK (1.3.0) and the iOS side binds GMA 13.x through Kotlin/Native cinterop, so the same `rememberAdManager()` call, the same `AdPlacement`, and the same `AdEvent` stream work on both platforms. The published coordinate is `dev.avinya.ads:admob-cmp` under the `dev.avinya.ads` group, at version 1.1.0. The Android app runs on API 26 or above and the iOS app targets iOS 15 or above. The library keeps AdMob’s vocabulary — `AdValue`, response info, adaptive banner sizes, UMP consent states, native asset names — but replaces the listener-style SDK surface with suspend functions, `StateFlow` state, and a single sealed `AdEvent` stream. You write the integration once and it runs identically on both platforms, with platform-specific behaviour isolated to thin Android and iOS adapters that the consumer never sees. Platform specifics stay where they belong: the Android app’s `AndroidManifest.xml` declares the AdMob app id, the iOS app’s `Info.plist` declares `GADApplicationIdentifier`, and everything in between is shared code. The split is deliberate. The library is published as two modules behind a single coordinate: `admob-cmp-core` holds the controllers, state machines, and platform adapters, while `admob-cmp-compose` holds the composable surface. Most consumers depend on the umbrella `dev.avinya.ads:admob-cmp` artifact and never notice the split. Apps that want the controller API without Compose Multiplatform can depend on `admob-cmp-core` directly. ## Which ad formats does it support? [Section titled “Which ad formats does it support?”](#which-ad-formats-does-it-support) Every format in the current AdMob catalogue, behind a single controller-per-format API: | Format | Controller | Composable | Guide | | -------------------------- | ------------------------------------------------------- | -------------- | ------------------------------------------ | | Banner (incl. collapsible) | `adManager.banner(placement)` | `BannerAdView` | [Banner ads](/formats/banner/) | | Interstitial | `adManager.interstitial(placement)` | — | [Interstitial ads](/formats/interstitial/) | | Rewarded | `adManager.rewarded(placement)` | — | [Rewarded ads](/formats/rewarded/) | | Rewarded interstitial | `adManager.rewardedInterstitial(placement)` | — | [Rewarded ads](/formats/rewarded/) | | App-open | `adManager.appOpen(placement)` + `AppOpenAdCoordinator` | — | [App-open ads](/formats/app-open/) | | Native | `adManager.nativeAd(placement)` (a pool) | `NativeAdView` | [Native ads](/formats/native/) | The controllers are placement-keyed and cached for the manager’s lifetime, so an app with three banner placements owns three `BannerAdController` instances — not a fresh one per recomposition. `NativeAdView` is the one exception in shape: it is a pool, because native ads are single-use. ## What does it give you that the raw SDKs do not? [Section titled “What does it give you that the raw SDKs do not?”](#what-does-it-give-you-that-the-raw-sdks-do-not) Four things the library owns so the app does not have to: 1. A placement-keyed controller cache so the same `AdPlacement` always resolves to the same instance with the same load state. 2. A TTL’d FIFO ad cache with capped exponential retry, configurable per placement through `AdCachePolicy`, `AdExpirationPolicy` and `AdRetryPolicy`. 3. A consent gate that makes a pre-consent ad request impossible by construction — every load checks `canRequestAds` and fails fast with `AdErrorCode.CONSENT_REQUIRED` when the user has not opted in. 4. One event stream instead of five callback interfaces, with `AdEvent` covering `Loaded`, `LoadFailed`, `Impression`, `Clicked`, `Paid`, `RewardEarned` and the iOS-only video family. The whole integration looks like this: 
```kotlin
@Composable
fun App() {
    val adManager = rememberAdManager()


    LaunchedEffect(Unit) {
        adManager.gatherConsentAndInitialize(
            AdConfig(
                androidAppId = TestAdIds.ANDROID_APP_ID,
                iosAppId = TestAdIds.IOS_APP_ID,
            )
        )
    }


    val placement = remember {
        AdPlacement(
            id = "main_interstitial",
            format = AdFormat.Interstitial,
            androidAdUnitId = TestAdIds.ANDROID_INTERSTITIAL,
            iosAdUnitId = TestAdIds.IOS_INTERSTITIAL,
        )
    }
    val interstitial = remember(adManager) { adManager.interstitial(placement) }
    val scope = rememberCoroutineScope()


    Button(
        onClick = {
            scope.launch {
                interstitial.load()
                interstitial.show()
            }
        }
    ) { Text("Show ad") }
}
```
 Two caveats worth knowing on day one. `show()` suspends for the ad’s whole on-screen lifetime, so it must run in a UI-scoped coroutine — never in `GlobalScope`. And a second `show()` on the same controller while one is still on screen returns `AdShowResult.NotReady` rather than queueing; await the first result before calling again. Both rules are documented in detail on the [interstitial guide](/formats/interstitial/). The cache and retry layer is the second thing people underestimate. A naive integration against the raw SDKs opens a TCP connection, calls GMA’s load, waits on a listener, parses the response, and only then exposes state. Every app that ships a full-screen ad eventually writes that caching, eviction, and retry layer themselves — usually wrong, and usually twice (once per platform). The library writes it once in shared code, with the policy surfaces the consumer needs (`AdCachePolicy`, `AdExpirationPolicy`, `AdRetryPolicy`, `AdTimeoutPolicy`) and nothing else. The [caching, retry and timeouts guide](/advanced/caching-retry-timeouts/) goes through every knob. ## How does it compare with other Kotlin Multiplatform AdMob libraries? [Section titled “How does it compare with other Kotlin Multiplatform AdMob libraries?”](#how-does-it-compare-with-other-kotlin-multiplatform-admob-libraries) A neutral look at capability, not at quality: | Capability | AdMob CMP | Typical Kotlin Multiplatform AdMob wrapper | | ----------------------------------------------- | ---------------------------------------------------- | ------------------------------------------ | | Banner, interstitial, rewarded | Yes | Yes | | Rewarded interstitial | Yes | Varies | | App-open ads | Yes | Usually not offered | | Native ads | Yes, with a layout DSL and an ad pool | Usually not offered | | UMP consent inside the init flow | Yes, with `ConsentMode` and the privacy options form | Usually a standalone consent call | | iOS ATT ordering handled explicitly | Yes | Varies | | Paid/revenue events and mediation response info | Yes | Varies | | Kotlin/Native test linking on iOS | Solved by a published Gradle plugin | Usually unaddressed | | iOS distribution model | Bindings-only cinterop; the app links GMA via SPM | Varies | The closest alternative in this space is [`LexiLabs-App/basic-ads`](https://github.com/LexiLabs-App/basic-ads). It covers banner, interstitial and rewarded formats. If those three formats are all a project needs and its API shape suits the codebase better, it is a reasonable choice. AdMob CMP exists for projects that also need native ads, app-open ads, consent wired into initialization, or Kotlin/Native tests that link on iOS. ## Which platforms and versions does it run on? [Section titled “Which platforms and versions does it run on?”](#which-platforms-and-versions-does-it-run-on) | Format | Android — GMA Next-Gen, API 26+ | iOS — GMA 13.x, iOS 15+ | Notes | | --------------------- | ------------------------------- | ----------------------- | ---------------------------------------------------------------------------------- | | Banner | ✔ Supported | ✔ Supported | Anchored adaptive, inline adaptive, fixed and fluid; collapsible on both platforms | | Interstitial | ✔ Supported | ✔ Supported | TTL'd FIFO cache, 1 hour | | Rewarded | ✔ Supported | ✔ Supported | RewardEarned event | | Rewarded interstitial | ✔ Supported | ✔ Supported | Same controller shape as Rewarded | | App-open | ✔ Supported | ✔ Supported | AppOpenAdCoordinator, cooldowns, blocking; cache TTL 4 hours | | Native | ✔ Supported | ✔ Supported | adLayout DSL and pooling on both; iOS renders through UIKit | | Capability | Android | iOS | Notes | | ----------------------------------------------------------------------------------------------------- | ---------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | UMP consent and privacy-options form | ✔ Supported | ✔ Supported | canRequestAds gates every request on both platforms | | App Tracking Transparency | — Not applicable | ✔ Supported | Android has no ATT: adManager.tracking always reports AdTrackingAuthorization.NotApplicable, and the AD\_ID manifest permission governs the advertising id there instead | | Mediation adapters | ✔ Supported | ✔ Supported | No adapters are bundled; add the ones you need | | Paid and revenue events | ✔ Supported | ✔ Supported | AdEvent.Paid carries AdValue and response info | | Native video events | ✖ Not available | ✔ Supported — five events | iOS emits VideoStarted, VideoPlayed, VideoPaused, VideoEnded and VideoMuted through GADVideoControllerDelegate. The Android GMA Next-Gen SDK exposes no equivalent callback surface on NativeAd, so Android emits none. This is an upstream SDK gap, not an admob-cmp omission — do not rely on native video events for cross-platform logic. | | immersiveMode, customClickGesture, publisherProvidedId, categoryExclusions, skipUninitializedAdapters | ✔ Supported | ✖ Silently ignored | Android-only request options | | customTargeting, placementId | ✔ Supported | ✔ Supported | Mapped on both platforms; placementId maps to placementID on iOS | Platform support matrix: six formats on Android and iOSCLAUDE.md invariants #11[Read this diagram in words](/reference/diagrams-in-words/#platform-matrix) Android is API 26 or above, with the GMA Next-Gen SDK and UMP arriving as transitive Maven dependencies. iOS is 15.0 or above, with the GMA and UMP frameworks linked by the app through Swift Package Manager. The full version table — Kotlin, Compose Multiplatform, Android `minSdk`, iOS deployment target, and the GMA / UMP versions each release was built against — is on [Compatibility](/reference/compatibility/). ## What does AdMob CMP deliberately not do? [Section titled “What does AdMob CMP deliberately not do?”](#what-does-admob-cmp-deliberately-not-do) A short list, because the omissions are features: * It ships zero mediation adapters by design. Adapters are platform binaries that must match the GMA SDK version and the publisher’s network contracts; bundling them would pin GMA versions for every consumer. Add them to your Android module and Xcode project directly. See [Mediation](/advanced/mediation/). * It never embeds Google’s binaries on iOS, only cinterop bindings. The app links the real GMA and UMP frameworks itself. See [Architecture](/reference/architecture/) for the rationale. * It is consumable from KMP and Gradle projects only, so a pure-Swift iOS app cannot adopt it without a Kotlin Multiplatform shim. * It does not support ad networks other than AdMob directly. Mediation covers that. ## Is AdMob CMP a consent management platform? [Section titled “Is AdMob CMP a consent management platform?”](#is-admob-cmp-a-consent-management-platform) No. In ad-tech, CMP normally means Consent Management Platform — the vendor that brokers GDPR / TCF consent. This library’s name predates that association in the project’s own history and is retained for continuity with the published Maven coordinate `dev.avinya.ads:admob-cmp`. It integrates Google’s User Messaging Platform to gather GDPR / TCF consent, but it is not itself a CMP vendor. The consent flow is documented on [UMP consent](/privacy/consent/). ## Where to next? [Section titled “Where to next?”](#where-to-next) [Quickstart](/start/quickstart/)Render a test ad in five minutes. [Installation](/start/installation/)Gradle, version catalog, and the Gradle plugin. [Native ads](/formats/native/)The layout DSL and ad pooling. [Compatibility](/reference/compatibility/)Kotlin, Compose, minSdk and iOS versions.

---

# Quickstart

> The fastest Compose Multiplatform AdMob setup — render a test ad in five minutes using Google's sample ad units, with no AdMob account required.

## What will you have at the end? [Section titled “What will you have at the end?”](#what-will-you-have-at-the-end) Five minutes from now, an Android or iOS app that renders a real banner ad inside a Compose Multiplatform screen, using Google’s public sample ad units. No AdMob account, no ad unit of your own, no App Store / Play Store ceremony. The integration is exactly the integration you will ship — only the test ids will be replaced with your own before release. The five minutes assume you already have a working Kotlin Multiplatform project with a Compose Multiplatform screen in `commonMain`. If you do not, start from the [KMP project wizard](https://kmp.jetbrains.com/) in your IDE; the only deviation from the default is adding the dependency line in the next step. ## How do I add the dependency? [Section titled “How do I add the dependency?”](#how-do-i-add-the-dependency) The quickstart deliberately uses Google’s sample ad units so no AdMob account is needed. The full installation story — version catalogs, the Gradle plugin, Kotlin/Native test linking — is on [Installation](/start/installation/). shared/build.gradle.kts 
```kotlin
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("dev.avinya.ads:admob-cmp:1.1.0")
        }
    }
}
```
 The Android GMA Next-Gen SDK and UMP arrive as transitive Maven dependencies, so no extra Android dependency is needed. iOS deliberately does not include the binaries — the app links them through Swift Package Manager. That sounds like extra work for a greenfield project, and it is the first time only: see [iOS setup](/start/ios-setup/) for the two package URLs and the three `Info.plist` keys. The [architecture reference](/reference/architecture/) explains why the distribution works that way. ## How do I initialize AdMob in Compose Multiplatform? [Section titled “How do I initialize AdMob in Compose Multiplatform?”](#how-do-i-initialize-admob-in-compose-multiplatform) Initialize once at the root of your app, ideally as a side effect on first composition. The library gathers consent and starts Mobile Ads in one call: 
```kotlin
@Composable
fun App() {
    val adManager = rememberAdManager()


    LaunchedEffect(Unit) {
        adManager.gatherConsentAndInitialize(
            AdConfig(
                androidAppId = TestAdIds.ANDROID_APP_ID,
                iosAppId = TestAdIds.IOS_APP_ID,
                testMode = true,
            )
        )
    }


    val status by adManager.status.collectAsState()
    if (status is AdManagerStatus.Ready) {
        AdScreen()
    }
}
```
 Each piece is doing real work. `rememberAdManager()` returns a process-wide singleton — the same one `AdMob.manager(context)` returns on Android, so there is never a second manager in a process. `gatherConsentAndInitialize` runs the UMP consent flow, invokes any initialization hooks, then starts Mobile Ads. And `status` is the gate the rest of the UI is built on: `AdManagerStatus` is `Idle`, `Initializing`, `ConsentRequired`, `Ready`, `Disabled(reason)`, or `Failed(error, retryable)`. A practical note on the gate: gating the entire ad screen on `Ready` is fine for the first integration, but the production app usually wants to preload placements in the background and only block the *first* show. The common shape is to keep showing app content while `Initializing`, and to flip the global UI gate the first time a `show()` button is pressed. The [interstitial guide](/formats/interstitial/) covers the preload-and-show pattern in detail. Initialization order: UMP consent, then ATT, then initializeThe required call order on iOS — gather UMP consent, request App Tracking Transparency authorisation, then initialize the ads SDK — and what Android reports instead. Initialization order: UMP consent, then ATT, then initializeCLAUDE.md invariants #5, #11[Read this diagram in words](/reference/diagrams-in-words/#init-sequence) The order on iOS matters. UMP consent, then App Tracking Transparency, then the first ad request — that is the only sequence that preserves the IDFA for personalised ads. [App Tracking Transparency](/privacy/app-tracking-transparency/) explains why requesting ads before ATT resolves permanently forfeits the IDFA for those requests. Caution `AdDebugOptions.testMode` configures **UMP consent debugging** only. It does **not** make GMA serve test ads. Only registering the device in `GlobalRequestConfiguration.testDeviceIds`, or using a `TestAdIds` unit, does that. See [Test safety](/advanced/test-safety/). ## How do I show my first banner? [Section titled “How do I show my first banner?”](#how-do-i-show-my-first-banner) 
```kotlin
val placement = remember {
    AdPlacement(
        id = "home_banner",
        format = AdFormat.Banner,
        androidAdUnitId = TestAdIds.ANDROID_BANNER,
        iosAdUnitId = TestAdIds.IOS_BANNER,
        strictTestMode = true,
    )
}


BannerAdView(
    placement = placement,
    modifier = Modifier.fillMaxWidth(),
    onEvent = { event ->
        when (event) {
            is AdEvent.Loaded -> println("banner loaded")
            is AdEvent.LoadFailed -> println("banner failed: ${event.error}")
            else -> Unit
        }
    },
)
```
 `BannerAdView` measures its own container, supplies the width, loads, attaches, refreshes and disposes the platform banner view for you. Setting `strictTestMode = true` throws at construction if the placement points at a production ad unit, which is exactly what you want in a debug build — a test build can never request live ads. The `remember` around the placement matters because controllers are placement-keyed and cached for the manager’s lifetime, so ids must be static and finite. The `onEvent` callback exposes the full `AdEvent` sealed hierarchy: `Loaded`, `LoadFailed`, `Impression`, `Clicked`, `OpenedFullScreen`, `ClosedFullScreen` and `Paid`. Most apps only log in development. Production code usually hoists ad events up to a single analytics collector — see [Revenue and paid events](/advanced/revenue-events/) for the paid-event shape and the cross-platform gotchas. ## Why is nothing rendering yet? [Section titled “Why is nothing rendering yet?”](#why-is-nothing-rendering-yet) A short triage, each item the one thing that is usually wrong: * The manager is not `AdManagerStatus.Ready` yet. Gate the UI on `status` before placing any `BannerAdView` or calling `load()`. * Consent has not been granted, so loads fail with `AdErrorCode.CONSENT_REQUIRED`. Run `gatherConsentAndInitialize` and check `adManager.consent.canRequestAds`. * The Android manifest is missing `com.google.android.gms.ads.APPLICATION_ID`. GMA crashes at startup if it is missing. See [Android setup](/start/android-setup/). * The iOS app has not added the two Swift Package Manager packages. See [iOS setup](/start/ios-setup/). * The banner placement uses `BannerRefreshPolicy.Manual` and nothing called `refresh()`. Manual policy is no auto-load; you must call `adManager.banner(placement).refresh()` yourself. * The UMP consent form was dismissed without a choice, so `canRequestAds` is still `false`. The privacy-options form must be reopened and the user must accept before any request reaches the network. When none of those explain it, the full symptom table is on [Troubleshooting](/reference/troubleshooting/). ## What changes before you ship? [Section titled “What changes before you ship?”](#what-changes-before-you-ship) Five swaps. None of them changes the structure of the integration: 1. Replace both sample app ids and every sample ad-unit id with your own. 2. Set `testMode = false` on `AdConfig`. Leaving it on means the consent debug settings still apply. 3. Keep `strictTestMode = true` in debug builds only. 4. Complete the [Play Data safety](/privacy/play-data-safety/) declaration in the Play Console. 5. Add `NSUserTrackingUsageDescription` to the iOS `Info.plist`, or every iOS request will serve non-personalised ads at materially lower eCPM. See [App Tracking Transparency](/privacy/app-tracking-transparency/). The test ids are recognisable on sight: `TestAdIds.ANDROID_BANNER` is `ca-app-pub-3940256099942544/9211549742`, which is the same id Google uses in its own sample apps. The release-time checklist above is the simplest way to keep a debug build from ever being mistaken for a release build once you are past the quickstart. ## Where to next? [Section titled “Where to next?”](#where-to-next) [Installation](/start/installation/)Version catalogs, modules, and the Gradle plugin. [iOS setup](/start/ios-setup/)SPM packages, Info.plist, ATT, and doctorIos. [UMP consent](/privacy/consent/)Consent modes and the privacy options form. [Troubleshooting](/reference/troubleshooting/)Symptom to cause to fix.

---

# Installation

> Add the Kotlin Multiplatform AdMob library dev.avinya.ads:admob-cmp with a version catalog, plus the Gradle plugin that fixes iOS test linking.

## How do I add AdMob CMP to a Kotlin Multiplatform project? [Section titled “How do I add AdMob CMP to a Kotlin Multiplatform project?”](#how-do-i-add-admob-cmp-to-a-kotlin-multiplatform-project) The artifact is a single umbrella coordinate that brings both the engine and the Compose surface. The Android GMA Next-Gen SDK and UMP arrive as transitive Maven dependencies, so no extra Android dependency is needed. iOS deliberately links Google’s frameworks in the app, not in the artifact. shared/build.gradle.kts 
```kotlin
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("dev.avinya.ads:admob-cmp:1.1.0")
        }
    }
}
```
 That is the whole dependency. Behind the umbrella artifact sits `admob-cmp-core` (the engine, controllers, platform adapters) and `admob-cmp-compose` (the composable surface). Most consumers depend on the umbrella `admob-cmp` and never need to know the split. Apps that want the controller API without Compose Multiplatform can depend on `admob-cmp-core` directly. The repository pattern matters less for a quickstart than for a long-lived project. A single shared module calling the ads API works fine for a small app, but most production projects split `commonMain` across modules by feature. The rules do not change with the module count: the dependency lives once in whichever module calls the controllers, and the Gradle plugin is applied in every module that compiles a Kotlin/Native test binary. ## Should I use a version catalog? [Section titled “Should I use a version catalog?”](#should-i-use-a-version-catalog) Yes for any non-trivial build. The library coordinate and the Gradle plugin id must stay on the same version, and a single `version.ref` makes that impossible to get wrong: gradle/libs.versions.toml 
```toml
[versions]
admob-cmp = "1.1.0"


[libraries]
admob-cmp = { module = "dev.avinya.ads:admob-cmp", version.ref = "admob-cmp" }


[plugins]
admob-cmp = { id = "dev.avinya.ads.admob-cmp", version.ref = "admob-cmp" }
```
 shared/build.gradle.kts 
```kotlin
commonMain.dependencies {
    implementation(libs.admob.cmp)
}
```
 When `VERSION_NAME` is bumped in `gradle.properties` for a release, the catalog entry moves in lockstep and every consuming module picks up the new version on the next Gradle sync. Without the catalog, the same bump becomes a search-and-replace across every `build.gradle.kts` in the project, and one of them is always missed. The plugin id lives in the same catalog as the library for the same reason: applying the plugin and depending on the library are two versions of the same statement, and the consumer should never be in a state where one of them is one version behind. ## Which modules do I put the dependency in? [Section titled “Which modules do I put the dependency in?”](#which-modules-do-i-put-the-dependency-in) The practical rule: put it in the shared module whose `commonMain` calls the ads API, once. Because controllers are placement-keyed and the manager is a process-wide singleton, adding it to several modules does not create several managers — but it does widen the set of modules whose Kotlin/Native test binaries need the Gradle plugin. Compose Multiplatform is required only if the composable surface (`BannerAdView`, `NativeAdView`, `rememberAdManager`) is used. The controller API — `AdManager`, the controllers, `AdPlacement` — has no Compose dependency. If a project only needs the controllers, depend on `admob-cmp-core` directly and skip `admob-cmp-compose`. A common arrangement is a `feature-ads` module that owns the `AdPlacement` list and the manager wiring, plus a `:shared` module that just consumes the controllers. Both still link to the same process-wide manager — there is no second instance — and only `feature-ads` needs the Gradle plugin if it is the only module with a Kotlin/Native test binary. ## Why do my iOS tests fail to link, and what fixes it? [Section titled “Why do my iOS tests fail to link, and what fixes it?”](#why-do-my-ios-tests-fail-to-link-and-what-fixes-it) This is the section that earns the page its inbound links, because the failure looks unrelated to ads. The app links Google’s frameworks through Swift Package Manager, but tests do not. `./gradlew :yourModule:iosSimulatorArm64Test` makes the Kotlin/Native compiler link a standalone executable with no Xcode, no `.xcodeproj` and no Swift Package Manager anywhere in the picture, so every symbol must resolve at that link — including the `GAD*` and `UMP*` classes these bindings reference. That is true **even if none of the tests touch ads.** The test binary contains the module’s whole main compilation, so any production code calling `rememberAdManager`, `NativeAdView` or the consent APIs drags those references in. A `FakeAdManager` does not help, because the requirement comes from the bindings being present in the link, not from anyone calling them. For faking ad *behaviour* in tests, the SDK ships `NoOpAdManager`. The fix: shared/build.gradle.kts 
```kotlin
plugins {
    id("dev.avinya.ads.admob-cmp") version "1.1.0"
}
```
 settings.gradle.kts 
```kotlin
pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
}
```
 Danger Adding another Swift Package Manager package will **not** fix a `:linkDebugTestIos…` failure. Only the Gradle plugin does. See [Troubleshooting](/reference/troubleshooting/) for the full symptom table. ## What does the Gradle plugin actually do? [Section titled “What does the Gradle plugin actually do?”](#what-does-the-gradle-plugin-actually-do) The plugin’s behaviour, exactly as implemented: * It registers `downloadGmaIos` and `downloadUmpIos`, which fetch the version-stamped GoogleMobileAds and UserMessagingPlatform XCFrameworks into `build/admob-cmp-ios-frameworks/` with a SHA-256 check. * It applies linker options **to test executables only** — `-framework GoogleMobileAds`, `-framework UserMessagingPlatform`, `-framework JavaScriptCore`, plus the Swift compatibility library directory. * It supports the `iosArm64` and `iosSimulatorArm64` targets. * It deliberately leaves the shipped app framework alone, because Kotlin/Native is supposed to leave those symbols undefined there for Xcode to bind via SPM. * It registers `doctorIos`, the diagnostic task. Off macOS, the plugin contributes no linker options, so Linux CI can still configure the build — it just cannot actually link a test executable. On macOS, the linker options are applied through Kotlin/Native’s `extraOpts`, which means the production app framework stays as a dynamic framework and Xcode still binds the SPM-resolved GMA at the final app link. That separation is the entire reason the published artifact is bindings-only on iOS. ## How do I verify the installation? [Section titled “How do I verify the installation?”](#how-do-i-verify-the-installation) Three tasks, in order: 
```bash
./gradlew :admob-cmp-core:doctorIos          # report-only; prints per-check status
./gradlew :shared:iosSimulatorArm64Test      # must link and run
./gradlew :shared:testAndroidHostTest        # JVM-side check
```
 `doctorIos` never fails the build — it is diagnostic only. It checks the framework download cache, whether the Xcode project references the SPM products, and whether `Info.plist` declares `GADApplicationIdentifier` and `SKAdNetworkItems`. The test tasks run the common-test suite on each platform’s runner and confirm the install is real, not just a Gradle sync. The [architecture reference](/reference/architecture/) describes what the test suite exercises. If a verification step fails, the first thing to check is the order: `doctorIos` reports missing pieces with file paths, and a test link failure prints the unresolved symbol name. The symbol name alone usually points at either the GMA package, the UMP package, or JavaScriptCore — and [Troubleshooting](/reference/troubleshooting/) has a table that maps each to the right fix. ## Where to next? [Section titled “Where to next?”](#where-to-next) [Android setup](/start/android-setup/)Manifest, AD\_ID, and Play Data safety. [iOS setup](/start/ios-setup/)SPM packages, Info.plist, ATT, and doctorIos. [Compatibility](/reference/compatibility/)Kotlin, Compose, minSdk and iOS versions. [Troubleshooting](/reference/troubleshooting/)Undefined GAD symbols and other link failures.

---

# Caching, retry and timeouts

> AdMob ad caching and retry on Kotlin Multiplatform — AdCachePolicy, AdExpirationPolicy, AdRetryPolicy and AdTimeoutPolicy, and how to size each one.

## Which knobs does AdMob CMP actually expose? [Section titled “Which knobs does AdMob CMP actually expose?”](#which-knobs-does-admob-cmp-actually-expose) Everything on this page is per-placement configuration on `AdPlacement`, so different placements can behave differently in the same app. The four policies and what each one bounds: The reason these are policies, not flags, is that the library must enforce a few invariants: `maxSize >= 1`, every TTL finite and positive, the backoff multiplier >= 1. A flag is a single value with no internal consistency; a policy is a small object whose constructor can validate the whole thing at one moment. Constructors throw, defaults are sensible, and a misconfigured placement fails at the construction site rather than at the first `load()`. | Policy | Bounds | Default | | -------------------- | ----------------------------------------------------------- | ----------------------------------------------------- | | `AdCachePolicy` | How many ads are held, and whether one reloads after a show | `maxSize = 1`, `reloadAfterShow = false` | | `AdExpirationPolicy` | How long a cached ad stays usable | 1h full-screen, 4h app-open, 1h native | | `AdRetryPolicy` | How a failed load is retried | 2 attempts, 2s initial delay, 30s cap, 2.0 multiplier | | `AdTimeoutPolicy` | How long a load or a presentation hand-off may take | 30s load, 10s presentation hand-off | ## How does the ad cache work? [Section titled “How does the ad cache work?”](#how-does-the-ad-cache-work) 
```kotlin
AdPlacement(
    id = "interstitial_level_end",
    format = AdFormat.Interstitial,
    adUnitIds = AdUnitIds(android = "…", ios = "…"),
    cachePolicy = AdCachePolicy(
        maxSize = 3,
        reloadAfterShow = true,
        expirationPolicy = AdExpirationPolicy(
            fullScreenTtl = 1.hours,
            appOpenTtl = 4.hours,
            nativeTtl = 1.hours,
        ),
    ),
)
```
 Full-screen ad lifecycle: load, cache, show, reloadCLAUDE.md invariants #1, #2, #9[Read this diagram in words](/reference/diagrams-in-words/#full-screen-lifecycle) The mechanics the diagram shows: the cache is a per-slot FIFO deque up to `maxSize`. `load()` fills it sequentially and a partial fill still reports `Loaded`. `show()` consumes the oldest entry first. Eviction happens on every touch. And `clear()` bumps a generation counter so any load or scheduled reload still in flight for the old generation is invalidated instead of repopulating a cache the caller just emptied. The constraint checks the constructors enforce, because they throw rather than clamp: `AdCachePolicy.maxSize` must be at least 1, and every duration in `AdExpirationPolicy` must be finite and positive. The cache also evicts on read, so a `load()` that finds expired entries drops them before reporting `Loaded` with the remaining valid count. A practical note on `load()` returning a partial fill. A partial fill happens when the platform SDK returns fewer ads than requested before the call resolves — usually because the network returned a smaller batch than the publisher asked for. The library still reports `Loaded` with whatever is in the cache, because the caller’s intent was “fill the cache”, and the cache is partially full. A call that returns zero ads is `Failed` with a no-fill error, not `Loaded` with an empty cache. A native-pool cross-reference in one sentence: for native placements the same `maxSize` budgets **available + in-use** ads together — see the [native ads guide](/formats/native/). ## When and how does a failed load retry? [Section titled “When and how does a failed load retry?”](#when-and-how-does-a-failed-load-retry) 
```kotlin
AdPlacement(
    id = "interstitial_level_end",
    format = AdFormat.Interstitial,
    adUnitIds = AdUnitIds(android = "…", ios = "…"),
    retryPolicy = AdRetryPolicy(
        maxAttempts = 2,          // total attempts, including the first
        initialDelay = 2.seconds,
        maxDelay = 30.seconds,
        backoffMultiplier = 2.0,
    ),
)
```
 Retry timeline: capped exponential backoffCLAUDE.md invariants #9[Read this diagram in words](/reference/diagrams-in-words/#retry-timeline) `maxAttempts` counts the **initial attempt plus retries**, so the default of 2 means one retry and `maxAttempts = 1` means none. Delay grows by `backoffMultiplier` after each attempt and is capped at `maxDelay`. The constructor requires `maxAttempts >= 1`, finite positive delays, `maxDelay >= initialDelay`, and `backoffMultiplier >= 1.0`. The classification, which is the part that surprises people: | Failure | Retried? | | ----------------------------------------------------------------------------------- | --------------------------------------------------- | | Network, timeout, internal error — GMA code `0`/`2` on Android, `2`/`5`/`11` on iOS | Yes, per `AdRetryPolicy` | | No fill — GMA code `3` on Android, `1` on iOS | No. This is normal; retry later at a natural moment | | `AdErrorCode.CONSENT_REQUIRED` | No. Resolve consent first | | `AdErrorCode.SDK_NOT_READY` | No. Wait for `AdManagerStatus.Ready` | A “no” here means the library does not schedule a retry. The publisher can still call `load()` again, of course — the policy is about automatic retries, not caller-initiated ones. A note on `maxAttempts = 1`. Setting `maxAttempts` to 1 disables the retry layer entirely — the call returns whatever the platform SDK returns, including transient failures. The right shape for that policy is a caller that has its own retry mechanism (a button-driven retry, a backoff at a higher level). The wrong shape is “I want to load faster” — `maxAttempts = 1` is not faster than `maxAttempts = 2` unless the network is consistently failing on the first try, in which case the underlying problem needs investigation, not a policy tweak. ## What stops a load or a presentation hanging forever? [Section titled “What stops a load or a presentation hanging forever?”](#what-stops-a-load-or-a-presentation-hanging-forever) 
```kotlin
AdPlacement(
    id = "interstitial_level_end",
    format = AdFormat.Interstitial,
    adUnitIds = AdUnitIds(android = "…", ios = "…"),
    timeoutPolicy = AdTimeoutPolicy(
        loadTimeout = 30.seconds,
        presentationHandOffTimeout = 10.seconds,
    ),
)
```
 Why this policy exists at all, because it is the least obvious of the four: GMA is a listener SDK, so if a terminal callback never arrives an unbounded `load()` or `show()` suspends forever. For `show()` that is worse than a hang — the presentation token is process-wide, so one wedged presentation blocks every full-screen ad in the app until the process dies. The precise semantics: `loadTimeout` is the maximum time for one load **including retry backoff**; on expiry the state becomes `AdLoadState.Failed` and a late ad is rejected and destroyed by the generation check, exactly as after a `clear()`. `presentationHandOffTimeout` bounds the time between committing an ad to presentation and the SDK reporting anything — it does **not** bound how long a user watches an ad. A note on why `presentationHandOffTimeout` exists. The platform SDKs present ads through a delegate-based pattern: the library hands the ad to the SDK and the SDK calls back when the presentation is complete. If the SDK never calls back — a real failure mode on iOS when the app is backgrounded mid-hand-off — the presentation token never releases, and the process-wide ad presence counter is permanently off-by-one. The timeout is the safety valve that releases the token after a bounded wait even if the SDK never reports. ## How should I size all of this? [Section titled “How should I size all of this?”](#how-should-i-size-all-of-this) Concrete recommendations rather than platitudes: * Interstitials at a natural break: `maxSize = 1`, `reloadAfterShow = true`. One ad, always warm. * Rewarded ads behind a user-initiated button: `maxSize = 1` and preload when the screen opens, so the button is never dead. * Bursty full-screen moments, such as end-of-level in a game: `maxSize = 2` or `3`, but only if all of them can plausibly be shown within the one-hour TTL. * Native feeds: size to the number of ad slots that can be on screen at once, plus one. * Raise `loadTimeout` only for genuinely slow networks; lowering it below about 10 seconds mostly converts fill into failures. The [native ads guide](/formats/native/) has the `maxSize`-for-native sizing in detail, because the same value budgets available plus in-use and the calculation is different. A note on “always warm”. The recommendation `reloadAfterShow = true` makes the cache refill in the background after each show, so the next break has an ad ready. The cost is the same as a regular `load()` — the publisher pays the network round-trip for a request that may or may not be shown. For a placement that fires ten times a day, that is ten extra requests; for a placement that fires twice a day, that is two. The math favours `reloadAfterShow = true` whenever the placement is in a hot path, and `false` when the placement is shown at a moment the user is unlikely to reach twice. ## Where to next? [Section titled “Where to next?”](#where-to-next) [Interstitial ads](/formats/interstitial/)The shared full-screen controller contract. [Native ads](/formats/native/)How maxSize budgets a pool. [Architecture](/reference/architecture/)Generation counters and the state machine. [Troubleshooting](/reference/troubleshooting/)No fill, timeouts, and error codes.

---

# Mediation

> AdMob mediation on Kotlin Multiplatform — adding adapters per platform, setting network privacy flags with hooks, and verifying fill.

## Why does AdMob CMP ship zero mediation adapters? [Section titled “Why does AdMob CMP ship zero mediation adapters?”](#why-does-admob-cmp-ship-zero-mediation-adapters) Adapters are platform binaries that must match the GMA SDK version and the publisher’s network contracts. Bundling them inside a cross-platform wrapper would pin versions for everyone and break the moment two artifacts carry the same Objective-C class. The property that makes this work on iOS specifically: because the library links nothing itself and ships bindings only, adapters resolve against the single copy of GMA in the app, so there is no duplicate-class problem. The full rationale is on [Architecture](/reference/architecture/). A consequence worth being explicit about: the same is *not* true on Android if an adapter is published as part of the Android module that also depends on `admob-cmp-core`. The GMA Android SDK uses a different mechanism — adapters register against a single singleton at runtime — so the duplicate-class problem does not arise, and bundling an adapter at the consumer side is the right shape. The [architecture reference](/reference/architecture/) has the full platform-by-platform model. ## How do I add an adapter on each platform? [Section titled “How do I add an adapter on each platform?”](#how-do-i-add-an-adapter-on-each-platform) 
```kotlin
// Android — app or shared Android module
dependencies {
    implementation("com.google.ads.mediation:facebook:…")
}
```
 On iOS, add the adapter’s Swift Package or CocoaPod to the Xcode project, alongside the `GoogleMobileAds` package added during [iOS setup](/start/ios-setup/). A few operational notes. Waterfalls and bidding are configured in the AdMob UI as normal. Mediated fill flows through every existing API with no special casing. And the adapter version must be compatible with the GMA version in the app on each platform independently, which is the main source of “it works on Android” reports. The [Play Data safety guide](/privacy/play-data-safety/) covers the disclosure side of enabling mediation. The “works on one platform” failure mode has a specific shape. An adapter version that is compatible with GMA 13.x on iOS may not be compatible with GMA Next-Gen 1.3.0 on Android, and the incompatibility surfaces as a missing-class crash at adapter init time, not as a graceful “this adapter is not loaded”. The fix is to check the adapter’s compatibility matrix per platform before adding the dependency, and to keep the GMA version consistent across the project’s two platforms even though the library does not enforce that. ## How do I set a network’s privacy flags before initialization? [Section titled “How do I set a network’s privacy flags before initialization?”](#how-do-i-set-a-networks-privacy-flags-before-initialization) State the problem first: many networks require privacy flags to be set *before* SDK initialization, and there is no cross-platform place to do that unless the ad library provides one. `AdInitializationHook` is that place. 
```kotlin
val metaConsentHook = object : AdInitializationHook {
    override suspend fun onPhase(phase: AdInitializationPhase, config: AdConfig) {
        when (phase) {
            AdInitializationPhase.BeforeConsentRequest -> Unit
            AdInitializationPhase.BeforeMobileAdsInitialize -> {
                // Call into the adapter's platform API behind an expect/actual:
                // Android: AdSettings.setDataProcessingOptions(arrayOf("LDU"))
                // iOS:     FBAdSettings.setDataProcessingOptions(["LDU"])
                applyNetworkPrivacyFlags()
            }
            AdInitializationPhase.AfterMobileAdsInitialize -> Unit
        }
    }
}


AdConfig(
    androidAppId = "ca-app-pub-…",
    iosAppId = "ca-app-pub-…",
    initializationHooks = listOf(metaConsentHook),
)
```
 Three properties precisely. The hook body is the caller’s code, so adapter-specific calls belong in `androidMain`/`iosMain` behind an `expect`/`actual` and are invoked from the hook. The three phases are `BeforeConsentRequest`, `BeforeMobileAdsInitialize` and `AfterMobileAdsInitialize`. And hooks run **exactly once per real native initialization attempt**, inside a detached scope, so cancelling one `initialize()` caller can never skip or duplicate a hook. The `expect`/`actual` pattern is the right shape for adapter privacy calls because the network SDKs are themselves platform-specific. The common side declares a suspending `applyNetworkPrivacyFlags()` function; `androidMain` calls `AdSettings.setDataProcessingOptions(arrayOf("LDU"))` (for Meta’s Limited Data Use flag) or the equivalent for the chosen network; `iosMain` does the same against the iOS class. The hook body stays the same on both platforms. Caution The Google Mobile Ads singleton initialises at most once per process. A second `initialize` call with the *same* effective config replays the first result; a call with a *different* app id or request configuration is **ignored with a logged warning**, not re-applied. Decide the settings before the first `initialize` ever runs. ## How do I verify an adapter is actually serving? [Section titled “How do I verify an adapter is actually serving?”](#how-do-i-verify-an-adapter-is-actually-serving) 
```kotlin
// After adManager.status is AdManagerStatus.Ready
adManager.diagnostics.adapterStatuses().forEach { status ->
    println("${status.adapterName}: initialized=${status.initialized} latencyMs=${status.latencyMillis}")
}


scope.launch { adManager.diagnostics.openAdInspector() }
```
 `AdapterInitializationStatus` carries `adapterName`, `initialized`, `latencyMillis` and `description`. `openAdInspector()` launches Google’s Ad Inspector overlay and works on test devices, and is the authoritative way to confirm an adapter serves. And `adManager.diagnostics.sdkVersion()` reports the underlying GMA version, which is the first thing to check against an adapter’s compatibility matrix. A practical note on `latencyMillis`. It is the time the adapter took to initialise, not the time it took to win an auction. A high value here means the adapter is taking long to register itself with GMA, which is sometimes an indication of a misconfigured network. A low value does not mean the adapter is winning impressions; it only means it is ready when GMA needs it. `openAdInspector()` is the right tool for “I want to see everything” — it overlays Google’s own inspector on the running app, with the live mediation chain for the current screen, the device’s ad requests in flight, and a way to fire test requests against specific ad units. It works only on test devices and never in release builds, because Google gates it behind a debug-only call path. The [test safety guide](/advanced/test-safety/) covers which devices count as test devices. ## How do I see which network won a given impression? [Section titled “How do I see which network won a given impression?”](#how-do-i-see-which-network-won-a-given-impression) 
```kotlin
LaunchedEffect(Unit) {
    adManager.events.collect { event ->
        if (event is AdEvent.Loaded) {
            val winner = event.responseInfo?.loadedAdNetworkResponseInfo
            println("won by ${winner?.adSourceName} (${winner?.adapterClassName}) in ${winner?.latencyMillis} ms")
        }
    }
}
```
 `AdResponseInfo.loadedAdNetworkResponseInfo` identifies the winning adapter while `adNetworkResponseInfos` is the whole mediation chain including the networks that failed, each with its own `error`. The failure entries in the chain are the fastest way to diagnose a mediation waterfall that is not filling, and they appear in `AdEvent.LoadFailed` as well as on successful loads with partial fills. `AdEvent.Paid` carries the mediated revenue for an impression, which is covered in detail on [Revenue and paid events](/advanced/revenue-events/). The chain visible on a paid event is the same chain visible on a load event — the mediation network that won is the same network that paid. A common debugging pattern: log the full `adNetworkResponseInfos` list on every `Loaded` event, and look for the `error` fields. A network that consistently appears in the chain with a non-null `error` is one that is being asked to bid and failing, which is different from a network that is not being asked. The former is a configuration issue; the latter is a waterfall issue. Both look the same to a publisher who only watches `loadedAdNetworkResponseInfo`. ## Where to next? [Section titled “Where to next?”](#where-to-next) [Revenue and paid events](/advanced/revenue-events/)AdValue and the mediation chain. [Play Data safety](/privacy/play-data-safety/)Adapters add data disclosures. [Architecture](/reference/architecture/)Why iOS ships bindings only. [iOS setup](/start/ios-setup/)Where adapter packages go in Xcode.

---

# Revenue and paid events

> Track the AdMob paid event on Kotlin Multiplatform — AdValue micros, precision, response info, and sending impression-level revenue to your analytics.

## How do I observe ad events at all? [Section titled “How do I observe ad events at all?”](#how-do-i-observe-ad-events-at-all) There are two collection points. `adManager.events` is a global `SharedFlow<AdEvent>` covering every placement, while each controller and pool exposes its own `events` for a single placement. Every `AdEvent` carries a `placementId`, which is what makes the global stream usable. 
```kotlin
LaunchedEffect(Unit) {
    adManager.events.collect { event ->
        when (event) {
            is AdEvent.Loaded -> println("loaded: ${event.placementId}")
            is AdEvent.LoadFailed -> println("failed: ${event.error}")
            is AdEvent.Impression -> println("impression: ${event.placementId}")
            is AdEvent.Clicked -> println("click: ${event.placementId}")
            is AdEvent.Paid -> println("revenue: ${event.paidEvent.value.valueMicros}")
            is AdEvent.RewardEarned -> println("reward: ${event.reward.type}")
            else -> Unit
        }
    }
}
```
 The full sealed set, once so readers stop guessing: `Loaded`, `LoadFailed`, `ShowFailed`, `Impression`, `Clicked`, `OpenedFullScreen`, `ClosedFullScreen`, `RewardEarned`, `Paid`, and the iOS-only `VideoStarted`, `VideoPlayed`, `VideoPaused`, `VideoEnded`, `VideoMuted`. Note that `Impression`, `Clicked` and `Paid` also carry an optional `adInstanceId`, which is what lets a paid event be joined to the impression it belongs to. A common pattern that does not work: collecting from a controller’s `events` flow inside the same composable that holds the controller. The collector’s `LaunchedEffect` outlives the controller on a screen exit, and the `events: SharedFlow<AdEvent>` is tied to the controller’s lifetime, so the collector silently stops receiving. The right shape is to collect from `adManager.events` (the global stream) at the root, and let the collector live for the lifetime of the manager. The per-controller `events` flow is useful for tests, where the controller’s lifetime is the test’s lifetime. ## How do I read impression-level revenue? [Section titled “How do I read impression-level revenue?”](#how-do-i-read-impression-level-revenue) 
```kotlin
LaunchedEffect(Unit) {
    adManager.events.filterIsInstance<AdEvent.Paid>().collect { event ->
        val value = event.paidEvent.value
        analytics.logAdRevenue(
            placementId = event.placementId,
            valueMicros = value.valueMicros,
            currency = value.currencyCode,
            precision = value.precision.name,
            adSource = event.paidEvent.responseInfo?.loadedAdNetworkResponseInfo?.adSourceName,
        )
    }
}
```
 The data shapes, stated exactly: * `PaidEvent` has `placementId`, `value: AdValue`, and `responseInfo: AdResponseInfo?`. * `AdValue` has `valueMicros: Long`, `currencyCode: String`, and `precision: AdValuePrecision`. * `AdValuePrecision` is `Unknown`, `Estimated`, `PublisherProvided` or `Precise`. The unit warning explicitly, because it is the most common analytics bug in this area: `valueMicros` is **millionths of a currency unit**. Dividing by 1,000,000 gives the value in `currencyCode`. Do not sum micros across currencies. A note on precision: `Estimated` values are modelled, not billed. Aggregating them is legitimate for pacing and LTV models, but they must never be presented to a user or a finance team as revenue. `PublisherProvided` is the value the publisher passed in via `AdValue(currencyCode, valueMicros, precision = PublisherProvided)` — a legitimate path for non-AdMob networks, and a value the library forwards untouched. `Precise` is the floor of trustworthy revenue; anything below is a model. A note on currency conversion. Each `AdValue` carries a `currencyCode` — a three-letter ISO 4217 code. Two paid events from different networks may have different `currencyCode`s; the right aggregation is to convert both to a single reporting currency at the moment of logging, not to mix micros across currencies. Mixing USD micros with EUR micros is the most common cause of “the eCPM went up by 30% after we changed networks” bugs. ## What does ResponseInfo tell me? [Section titled “What does ResponseInfo tell me?”](#what-does-responseinfo-tell-me) 
```kotlin
val info: AdResponseInfo? = event.paidEvent.responseInfo
println(info?.responseId)                                  // unique response identifier
println(info?.adapterClassName)                            // adapter that loaded it
println(info?.loadedAdNetworkResponseInfo?.adSourceName)   // winning network
info?.adNetworkResponseInfos?.forEach { network ->
    println("${network.adSourceName}: ${network.latencyMillis} ms, error=${network.error?.message}")
}
```
 `AdResponseInfo` carries `responseId`, `adapterClassName`, `extras`, `loadedAdNetworkResponseInfo` and `adNetworkResponseInfos`. Each `AdNetworkResponseInfo` carries `adapterClassName`, `latencyMillis`, `error`, `adSourceName`, `adSourceId`, `adSourceInstanceName` and `adSourceInstanceId`. The failure entries in the chain are the fastest way to diagnose a mediation waterfall that is not filling — see the [mediation guide](/advanced/mediation/) for the chain shape and the failure interpretation. A note on `extras`: it is a `Map<String, String>` of adapter-specific metadata. Some networks use it to attach internal trace ids; Google’s own GMA uses it for the response’s correlation id under the key `ResponseInfo`. Treat it as opaque metadata, but never log the full map to production analytics — some adapters put personally identifying information in it, and that data is yours, not Google’s. A common use of `extras` is to forward the winning network’s internal id into the app’s analytics pipeline. The [mediation guide](/advanced/mediation/) has the matching configuration step. A `Map<String, String>` of unknown shape should be flattened into a typed structure before forwarding — analytics systems that accept free-form fields tend to grow untyped schemas that are hard to evolve. The recommended shape for an in-house analytics target is a schema migration per network: a v1 entry for AdMob, a v2 entry for Meta, a v3 entry for the next network, and the analytics upstream keeps the historical records. Free-form forwarding is faster to ship and slower to retire. ## How should I send this to analytics? [Section titled “How should I send this to analytics?”](#how-should-i-send-this-to-analytics) Three short points, drawn from production patterns: * Collect in one place rather than per-composable so events are not double-counted across recompositions. The natural shape is a single `LaunchedEffect(Unit)` that subscribes to `adManager.events` for the lifetime of the root composition. * Key on `placementId` plus `adInstanceId` when correlating impressions and revenue. The same `adInstanceId` appears on the `Impression` event and on the `Paid` event for the same ad, which is what makes the join exact. * These events are observation — they are not the mechanism for granting rewards, which is covered on [Rewarded ads](/formats/rewarded/). The double-grant warning there applies here in a milder form: do not pay out from both a paid event and a callback. A practical note on `Loaded` versus `Paid` for revenue attribution. `Loaded` fires when the platform SDK reports a successful load; `Paid` fires when the user has actually seen the ad. The two are not the same moment, and the gap between them can be many seconds for video. Analytics that join “loads” to “revenue” without a window will over-count; the right join key is `adInstanceId`, and the right window is the lifetime of the ad. A second practical note: `Paid` events are delivered to the collector in order, but `Paid` for one ad can race with `Impression` for the same ad. The collector’s coroutine context determines which is observed first, and “first” is not necessarily “emitted first” — the platform SDKs are free to fire callbacks on background threads, and the library serialises them on `Dispatchers.Main.immediate`. The ordering guarantee is that callbacks for the same ad arrive in causal order (Loaded before Impression before Paid); cross-ad ordering is not guaranteed. ## Where to next? [Section titled “Where to next?”](#where-to-next) [Mediation](/advanced/mediation/)Reading the waterfall behind a paid event. [Rewarded ads](/formats/rewarded/)Why events are not the grant point. [Architecture](/reference/architecture/)How events flow from the platform SDKs.

---

# Test safety

> AdMob test ads on Kotlin Multiplatform — why testMode does not serve test ads, what strictTestMode guards, and how to keep live ads out of debug builds.

## Why are there two different test flags? [Section titled “Why are there two different test flags?”](#why-are-there-two-different-test-flags) The confusion this page exists to remove, stated as an `<Aside type="danger">`: > **`testMode` and `strictTestMode` are not the same flag, and neither one does what the other does.** `AdDebugOptions.testMode` configures **UMP consent debugging** only. It does **not** make Google Mobile Ads serve test ads. `AdPlacement.strictTestMode` is the safety guard: it **throws at construction** if the placement points at a production ad unit. A small table so the distinction sticks: | Flag | Lives on | Affects | Default | | ---------------- | ----------------------------- | --------------------------------------------------------------- | ------- | | `testMode` | `AdConfig` / `AdDebugOptions` | UMP consent debugging: debug geography and consent test devices | `false` | | `strictTestMode` | `AdPlacement` | Construction-time validation of the ad unit ids | `false` | The reason there are two flags is that they guard different layers. `testMode` affects the consent flow; `strictTestMode` affects the ad request. A debug build that sets `testMode = true` and uses a real ad unit is requesting live ads with consent debug enabled, which is the configuration that gets AdMob accounts suspended. A debug build that sets `strictTestMode = true` and uses a test ad unit is testing the consent flow safely. The flags are independent and the debug build needs both, configured correctly. ## What does testMode actually configure? [Section titled “What does testMode actually configure?”](#what-does-testmode-actually-configure) `testMode` gates the UMP debug settings: `consentDebugGeography` and `consentTestDeviceIds` change nothing unless `testMode` is `true`. The library ships a guardrail: if `testMode` is `true` and no test device ids are configured anywhere, the SDK logs a warning at initialization rather than silently doing nothing — because in that state requests may serve **live** ads. The warning is not a substitute for fixing the configuration; it is a hook to make the misconfiguration visible. A note on what `testMode` does *not* do. It does not make the GMA network serve test ads, it does not register the device for test traffic, and it does not change the ad unit ids the placements point at. The only thing it does is unlock the UMP-side debug fields. The “test” name in the flag is unfortunate — it is a consent-debug flag, not a “test ads” flag — and the [UMP consent guide](/privacy/consent/) has the full semantics. ## How do I actually get test ads? [Section titled “How do I actually get test ads?”](#how-do-i-actually-get-test-ads) From exactly two places: 
```kotlin
// 1. Google's official sample ad units — always test, on any device
AdPlacement(
    id = "banner_home",
    format = AdFormat.Banner,
    androidAdUnitId = TestAdIds.ANDROID_BANNER,
    iosAdUnitId = TestAdIds.IOS_BANNER,
    strictTestMode = true,
)


// 2. Your production ad units, on a registered test device
AdConfig(
    appIds = AdAppIds(android = "ca-app-pub-…", ios = "ca-app-pub-…"),
    globalRequestConfiguration = GlobalRequestConfiguration(
        testDeviceIds = listOf("YOUR-DEVICE-HASH"),
    ),
)
```
 Emulators and simulators qualify as test devices automatically. A physical device needs its hashed id — printed to logcat or the Xcode console on the first unregistered request. `TestAdIds` also exposes `ANDROID_APP_ID` and `IOS_APP_ID`, plus ready-made `debugAdConfig` and `debugAdPlacements` values for a complete test setup. The two paths serve different purposes. Path 1 is the right shape for an integration test or a debug build that needs to render a real ad layout with a real ad network; the test ids are guaranteed to serve an ad. Path 2 is the right shape for a QA build that needs to test the publisher’s real ad units without generating billable impressions; the device hash routes those requests to test inventory. A common misuse is to combine the two paths. A debug build that sets `strictTestMode = true` *and* registers a test device hash in `GlobalRequestConfiguration.testDeviceIds` is doubly safe and twice as much configuration to maintain. Pick the path that matches the build’s purpose: an internal dev build wants path 1 (Google’s test ids, no publisher configuration needed); a QA build that exercises the publisher’s real ad units wants path 2 (test device hash, real unit ids, `strictTestMode = false`). Mixing them obscures which test mode is active. ## What does strictTestMode protect me from? [Section titled “What does strictTestMode protect me from?”](#what-does-stricttestmode-protect-me-from) The failure it prevents and why it fails closed. Because `testMode` only affects UMP, a developer who trusts it requests **real** ads against production ad units from a debug build. That is invalid traffic, and invalid traffic gets AdMob accounts suspended. A warning was judged insufficient; the check throws. 
```kotlin
// Throws IllegalArgumentException at construction
AdPlacement(
    id = "banner_home",
    format = AdFormat.Banner,
    androidAdUnitId = "ca-app-pub-1234567890123456/1234567890",  // production unit
    iosAdUnitId = "ca-app-pub-1234567890123456/0987654321",
    strictTestMode = true,
)
```
 The exception message names the placement and the offending ad unit ids. The escape hatch is deliberate and explicit: set `strictTestMode = false` when live ads in that build are genuinely intended. Production builds ship with `strictTestMode = false`; debug builds ship with `strictTestMode = true`. A note on what the exception is *not*. It is not a runtime check; it fires at construction. That means a placement built inside a `remember { … }` block in a Compose tree will throw on the first composition, not on the first ad request. The benefit is that the misconfiguration is caught before any network traffic; the cost is that the exception surfaces in a context that is sometimes hard to map back to the offending placement. The exception message names the placement id, which is the key. ## How should I wire this into debug and release builds? [Section titled “How should I wire this into debug and release builds?”](#how-should-i-wire-this-into-debug-and-release-builds) The shape a real app should use — one flag, threaded through: 
```kotlin
// A single build-time flag, e.g. from BuildConfig or an expect/actual
val isDebugBuild: Boolean = /* … */


val placements = listOf(
    AdPlacement(
        id = "banner_home",
        format = AdFormat.Banner,
        adUnitIds = if (isDebugBuild) {
            AdUnitIds(android = TestAdIds.ANDROID_BANNER, ios = TestAdIds.IOS_BANNER)
        } else {
            AdUnitIds(android = "ca-app-pub-…/…", ios = "ca-app-pub-…/…")
        },
        strictTestMode = isDebugBuild,
    )
)
```
 The release checklist: `testMode = false`, no debug geography, no consent test device ids, real app ids in the Android manifest and the iOS `Info.plist`, and real ad unit ids in every placement. Each item is a checkbox, and missing one is the difference between a release build and a debug build that has been signed and uploaded by accident. A related release-checklist item that is easy to forget: the [Play Data safety form](/privacy/play-data-safety/) and the [iOS Info.plist](/start/ios-setup/) must be aligned with the production ad units. A release build that uses Google’s sample ad ids will serve Google’s sample ads in production, which is a different kind of bug than a debug build that serves live ads — both fail the publisher’s expectations, both come from the same misconfiguration, and both are caught by the same release-time checklist. ## Where to next? [Section titled “Where to next?”](#where-to-next) [UMP consent](/privacy/consent/)Where testMode actually applies. [Quickstart](/start/quickstart/)The sample-ad-unit path. [Troubleshooting](/reference/troubleshooting/)When strictTestMode throws.

---

# App-open ads

> KMP app-open ads with AppOpenAdCoordinator — foreground detection, minimum background duration, cooldowns, blocking, and the four-hour ad TTL.

## What are app-open ads and when do they show? [Section titled “What are app-open ads and when do they show?”](#what-are-app-open-ads-and-when-do-they-show) App-open ads show while the app is loading, typically when a user returns to it from the background. They are a full-screen format with its own TTL (four hours, not the one-hour default of other full-screen formats) and its own lifecycle plumbing because the trigger is process state, not user action. The format is unusually easy to get wrong because it depends on the app’s lifecycle plumbing working correctly, and the consequence of getting it wrong is an ad showing at the wrong moment — over a consent form, during a purchase, or when the user did not actually return. `AppOpenAdCoordinator` is the library’s answer to that problem. It implements the entire recommended lifecycle: preload, foreground detection, minimum-background gating, cooldown, and reload after consumption. Hand-rolling the same behaviour is the most common source of app-open ad bugs, and the coordinator exists to make the hand-rolled version unnecessary. A note on naming: this is the only controller in the library with a coordinator layer above it. The interstitial, rewarded, rewarded interstitial, and native controllers are all single-instance — their controllers carry their own state. The app-open format is different because its trigger is process lifecycle, not user action, and the state that drives the trigger lives outside the controller. The coordinator is the bridge between the platform lifecycle APIs and the controller API. ## How do I wire up AppOpenAdCoordinator? [Section titled “How do I wire up AppOpenAdCoordinator?”](#how-do-i-wire-up-appopenadcoordinator) 
```kotlin
val placement = remember {
    AdPlacement(
        id = "app_open_main",
        format = AdFormat.AppOpen,
        androidAdUnitId = TestAdIds.ANDROID_APP_OPEN,
        iosAdUnitId = TestAdIds.IOS_APP_OPEN,
    )
}


val coordinator = remember(adManager) {
    AppOpenAdCoordinator(
        manager = adManager,
        controller = adManager.appOpen(placement),
        config = AppOpenConfig(
            minBackgroundDuration = 4.seconds,
            cooldownBetweenShows = 4.hours,
            preloadOnStart = true,
            showOnColdStart = false,
        ),
    )
}


LaunchedEffect(Unit) { coordinator.start(this) }
```
 `start(scope)` binds the coordinator to a coroutine scope and begins observing foreground transitions. `stop()` tears it down. The coordinator must be created inside `remember` so a recomposition does not build a second one and double-register the lifecycle observer. ## What does each AppOpenConfig setting do? [Section titled “What does each AppOpenConfig setting do?”](#what-does-each-appopenconfig-setting-do) | Setting | What it does | | ----------------------- | ------------------------------------------------------------------------------------------------------------------- | | `minBackgroundDuration` | Ignore quick app switches. A return sooner than this does not trigger a show. | | `cooldownBetweenShows` | Minimum gap between two app-open impressions. `Duration.ZERO` disables the cooldown. | | `preloadOnStart` | Load an ad as soon as the coordinator starts, so the first eligible return has inventory. | | `showOnColdStart` | Whether a cold start may show an ad. Read the KDoc before enabling — a cold-start ad competes with your own splash. | | `coldStartTimeout` | How long a cold start may wait for an ad before giving up and continuing into the app. | A short `minBackgroundDuration` maximises impressions and annoys users who switch apps to copy a code; four seconds is a reasonable floor. A `cooldownBetweenShows` of a few hours keeps the format from feeling like an ad wall. The judgement call on `showOnColdStart`: a cold-start ad competes with the app’s own splash for the user’s attention. Most apps have a meaningful cold-start experience (a logo, a sign-in flow, a first-run tutorial) and disabling cold-start shows is the right choice. Apps with a near-instant cold start can enable it, but should still gate the show behind a short `coldStartTimeout` so the user never waits on the ad network. A note on the `Duration` values: `4.seconds`, `4.hours`, `30.seconds` all come from `kotlin.time.Duration.Companion`. The constructor does not clamp — passing `Duration.ZERO` to `cooldownBetweenShows` disables the cooldown, passing a negative value throws, and passing a very long cooldown is honoured verbatim. The defaults are designed for the common case, not edge cases. ## How do I stop an app-open ad interrupting checkout? [Section titled “How do I stop an app-open ad interrupting checkout?”](#how-do-i-stop-an-app-open-ad-interrupting-checkout) 
```kotlin
coordinator.isBlocked = true    // entering checkout or onboarding
// …
coordinator.isBlocked = false   // flow finished
```
 Set `isBlocked = true` during a purchase, during onboarding, and whenever another full-screen ad may show. The property is a plain mutable field, so it is the caller’s job to reset it — a `try`/`finally` around the sensitive flow is the safe shape. The blocking check is evaluated at the moment a show would otherwise happen, not at the moment `isBlocked` is set. That means an in-flight show that has already passed the check will not be cancelled by setting `isBlocked = true` afterwards. The property is a guard against the *next* eligible show, not a kill switch for the current one. In practice that distinction rarely matters, because the gap between the check and the actual show is well under a second; on iOS it is the gap between `WillEnterForeground` and the SDK’s `presentFromRootViewController:` call. A common related mistake: setting `isBlocked = true` inside the `onEvent` callback of another full-screen ad. That works, but only if the callback fires *before* the user returns to the foreground. The safer shape is to set the flag at the entry point of the sensitive flow and clear it at the exit, in a `try`/`finally` so a thrown exception cannot leak the blocked state. ## Why did my app-open ad not show? [Section titled “Why did my app-open ad not show?”](#why-did-my-app-open-ad-not-show) A short triage: * The SDK is not `AdManagerStatus.Ready`, and the coordinator deliberately shows only when it is, so it can never appear over a consent form. This also means it works under `ConsentMode.SkipConsent`. * The background interval was shorter than `minBackgroundDuration`. * The cooldown has not elapsed. * `isBlocked` is still `true` because a flow set it and never reset it. * No fresh ad was cached, in which case the coordinator reloads automatically. * On iOS the coordinator listens to `WillEnterForeground`, so system alerts and consent-form dismissals do not trigger shows. On Android it uses `ProcessLifecycleOwner`. The full symptom table is on [Troubleshooting](/reference/troubleshooting/). ## Can I control app-open ads manually? [Section titled “Can I control app-open ads manually?”](#can-i-control-app-open-ads-manually) 
```kotlin
val appOpen = adManager.appOpen(placement)
scope.launch {
    appOpen.load()
    appOpen.showIfAvailable()   // shows only when isReady()
}
```
 `AppOpenAdController` is an ordinary `FullScreenAdController` plus `showIfAvailable()`. The `showIfAvailable()` convenience is a no-op when `isReady()` is `false` rather than returning `AdShowResult.NotReady` — useful for a single-tap flow where the caller does not want to handle a not-ready branch. Hand-rolling the lifecycle means reimplementing foreground detection, cooldowns, minimum-background gating, and reload after consumption, which is the coordinator’s entire reason to exist. Most production code should use the coordinator; the manual path exists for tests and for apps that have a custom foreground detector they need to integrate with. The full surface of `AppOpenAdCoordinator` is therefore: a constructor taking the manager, controller, and config; `start(scope)` to begin observing; `stop()` to release the observer; and the mutable `isBlocked` field. There is no public method to “force a show” or “reload now” — those operations are the coordinator’s internal contract, and exposing them would let a caller defeat the cooldown and minimum-background gating the coordinator exists to enforce. A short note on `stop()`: it is the symmetric counterpart to `start(scope)` and should be called from the same lifecycle where `start` was called. In a Compose app, the typical pattern is `DisposableEffect(coordinator) { onDispose { coordinator.stop() } }` so the observer is released on screen exit. Forgetting `stop()` is not catastrophic — the next `start` will replace the observer — but it does leak the previous `WillEnterForeground` / `ProcessLifecycleOwner` listener until the coordinator is garbage-collected. ## Where to next? [Section titled “Where to next?”](#where-to-next) [Interstitial ads](/formats/interstitial/)The shared full-screen controller contract. [UMP consent](/privacy/consent/)Why app-open never covers a consent form. [Caching, retry and timeouts](/advanced/caching-retry-timeouts/)TTLs and the four-hour app-open default. [Troubleshooting](/reference/troubleshooting/)When an ad does not appear.

---

# Banner ads

> AdMob banners in Compose Multiplatform — BannerAdView, adaptive and collapsible size policies, refresh policies, and how banner width is resolved.

## How do I show a banner ad in Compose Multiplatform? [Section titled “How do I show a banner ad in Compose Multiplatform?”](#how-do-i-show-a-banner-ad-in-compose-multiplatform) Size and refresh behaviour come from the **placement**, not from composable parameters, which is why the same banner behaves identically whether it is driven from Compose or headlessly. The full AdMob Compose Multiplatform banner integration: 
```kotlin
val placement = remember {
    AdPlacement(
        id = "banner_home",
        format = AdFormat.Banner,
        adUnitIds = AdUnitIds(
            android = TestAdIds.ANDROID_BANNER,
            ios = TestAdIds.IOS_BANNER,
        ),
    )
}


BannerAdView(
    placement = placement,
    modifier = Modifier.fillMaxWidth(),
    onEvent = { event ->
        when (event) {
            is AdEvent.Loaded -> println("banner loaded")
            is AdEvent.LoadFailed -> println("banner failed: ${event.error}")
            is AdEvent.Paid -> println("revenue: ${event.paidEvent.value.valueMicros}")
            else -> Unit
        }
    },
)
```
 `BannerAdView` resolves the width from its constraints (overridable with the `widthDp` parameter), sizes its height from the returned ad size, and clears the controller on dispose. The `remember` around the placement matters because controllers are cached per placement id for the manager’s lifetime and are never auto-evicted, so ids must be static and finite. The [architecture reference](/reference/architecture/) explains why the cache exists. A subtle but important property: the same `BannerAdView` composable is reused across recompositions of the same screen, so its `onEvent` callback fires for every state change of the placement. The recommendation is to hoist ad events to a single collector rather than react in place, both for analytics accuracy and to keep recomposition work bounded. The [revenue and paid events guide](/advanced/revenue-events/) has the full event-stream pattern. ## Which banner size should I use? [Section titled “Which banner size should I use?”](#which-banner-size-should-i-use) 
```kotlin
AdPlacement(
    id = "banner_home",
    format = AdFormat.Banner,
    adUnitIds = AdUnitIds(android = "…", ios = "…"),
    bannerSizePolicy = AdSizePolicy.LargeAnchoredAdaptive(),   // default
)
```
 | Policy | What it maps to | Use it when | | ------------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------- | | `AdSizePolicy.LargeAnchoredAdaptive(collapsible)` | Large anchored adaptive | The banner is pinned to the top or bottom of the screen. This is the default. | | `AdSizePolicy.InlineAdaptive(maxHeightDp)` | Inline adaptive | The banner sits inside scrolling content and may be taller. | | `AdSizePolicy.Fixed(widthDp, heightDp)` | A fixed custom size | You need an exact size and accept lower fill. | | `AdSizePolicy.Fluid` | Fluid | The container dictates the size. | Anchored adaptive is the right default because it lets AdMob pick the best height for the device width. Inline adaptive is for feeds, where `maxHeightDp` bounds how much of the viewport an ad may take. Fixed sizes reduce eligible demand and should be a deliberate choice — they make sense for a custom layout slot that other UI elements measure against, and almost nowhere else. A practical note on heights: anchored adaptive returns a height that matches the device’s current orientation. A banner at the bottom of the screen in portrait may grow when the device rotates to landscape, which is correct behaviour for an anchored ad and is the reason the size comes from the platform SDK rather than from a fixed number. ## How do collapsible banners work? [Section titled “How do collapsible banners work?”](#how-do-collapsible-banners-work) 
```kotlin
bannerSizePolicy = AdSizePolicy.LargeAnchoredAdaptive(
    collapsible = CollapsiblePlacement.Bottom,
)
```
 `CollapsiblePlacement` is `Top` or `Bottom`. Collapsible is a property of the anchored adaptive policy rather than a separate format. The part that wastes people’s afternoons: **regular banner test ids never serve collapsible fill.** Testing requires `TestAdIds.ANDROID_COLLAPSIBLE_BANNER` and `TestAdIds.IOS_COLLAPSIBLE_BANNER`. With regular test ids, the banner loads and renders normally, but never collapses, which looks like a bug in the size policy rather than a test-id mismatch. Collapsible banners expand on a user tap and stay expanded until the user dismisses them, then return to a small anchor at the configured edge of the screen. They are subject to AdMob’s collapsible-specific policies, and the publisher’s AdMob account must have collapsible enabled — a unit from an account without collapsible enabled behaves the same as a regular banner. ## How often does a banner refresh? [Section titled “How often does a banner refresh?”](#how-often-does-a-banner-refresh) 
```kotlin
AdPlacement(
    id = "banner_home",
    format = AdFormat.Banner,
    adUnitIds = AdUnitIds(android = "…", ios = "…"),
    bannerRefreshPolicy = BannerRefreshPolicy.SdkManaged(60.seconds),
)
```
 | Policy | Behaviour | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `BannerRefreshPolicy.AdServerManaged` | The default. No client timer; configure refresh in the AdMob UI. | | `BannerRefreshPolicy.SdkManaged(interval)` | Client-side reload every `interval`, enforced to the 30s–120s range, only while the app is foregrounded, and it waits for an in-flight load to settle. | | `BannerRefreshPolicy.Manual` | No automatic load at all. Call `adManager.banner(placement).refresh()` yourself. | Caution With `Manual`, nothing loads until `refresh()` is called, and `refresh()` fails if nothing has been loaded yet — so a `Manual` banner that has never been composed and loaded renders nothing. This is the single most common “my banner is blank” cause. The `SdkManaged` 30s–120s range is enforced because AdMob’s policy treats banners refreshing faster than 30 seconds as invalid traffic. Outside that range, the constructor clamps silently rather than throwing, which is the design choice that lets the same placement work across reasonable timer settings without forcing the caller to validate. ## How is the banner width resolved? [Section titled “How is the banner width resolved?”](#how-is-the-banner-width-resolved) A banner’s width is an **input**, not something the SDK can always discover. `BannerAdView` measures its own container and supplies it. A headless caller must supply it: 
```kotlin
adManager.banner(placement).load(geometry = BannerGeometry(widthDp = 320))
```
 Banner geometry: host-supplied width to resolved adaptive sizeCLAUDE.md invariants #6[Read this diagram in words](/reference/diagrams-in-words/#banner-geometry) `load()` previously took `(sizePolicy, requestOptions)` and resolved its own width — from an `Activity` on Android and from `UIScreen.mainScreen` on iOS. The iOS path silently produced full-screen width in iPad split view, Slide Over and popovers, sizing every banner wrong with no error. Width is now a host-supplied input: `load(geometry, sizePolicy, requestOptions)`. Existing no-argument `load()` calls still compile because `geometry` defaults to `null`, but a headless call with no geometry now **fails** rather than guessing when the platform cannot resolve a width. `refresh()` replays the **whole** resolved request — geometry, size policy and request options — from the most recent `load()`. It previously kept only the resolved size and rebuilt options from `placement.requestOptions`, silently dropping any custom `AdRequestOptions` the original `load()` was given. It fails if nothing has been loaded yet. The fix is part of the 1.1.0 release and is the kind of behaviour change that is invisible until the day you depend on it. The [changelog](/reference/changelog/) entry for 1.1.0 calls it out explicitly. ## Can I use banners without Compose? [Section titled “Can I use banners without Compose?”](#can-i-use-banners-without-compose) Yes. `adManager.banner(placement)` returns a `BannerAdController` with `load(geometry, sizePolicy, requestOptions)`, `refresh()`, `clear()`, `loadState: StateFlow<AdLoadState>`, `events: SharedFlow<AdEvent>`, and `placement`. The controller does not host a view — the caller is responsible for that. `BannerAdView` is the recommended path for anything Compose-rendered, because it measures its own container correctly; the headless path is for custom Android Views, for UIKit code, and for unit tests that need to drive a banner directly. A typical headless use case is a banner embedded in an `AndroidView` inside Compose, where the underlying view is a real platform widget the app manages. The controller API gives that widget a `loadState` it can observe and an `events` flow it can pipe into the rest of the app’s analytics. The geometry parameter is mandatory in this case, because there is no Compose `Modifier` to measure. ## Why is my banner blank? [Section titled “Why is my banner blank?”](#why-is-my-banner-blank) Each line is one common cause: * The manager is not `AdManagerStatus.Ready` yet. Gate on `status` before placing any `BannerAdView`. * Consent has not been granted, so loads fail with `AdErrorCode.CONSENT_REQUIRED`. Check `adManager.consent.canRequestAds`. * The policy is `Manual` and nothing has called `refresh()`. Switch to `SdkManaged` or compose the view and call `refresh()` explicitly. * The ad unit has no fill right now, which surfaces as GMA code `3` on Android and `1` on iOS. That is normal; it is not a configuration error and is not retried. * A headless `load()` was issued with no geometry on a platform that cannot resolve a width. The library now fails rather than guessing. The full symptom table is on [Troubleshooting](/reference/troubleshooting/). One more thing worth knowing: a banner that loaded once and is now returning “no fill” is not a configuration error. AdMob’s fill rate fluctuates by region, time of day, and ad unit age, and the right behaviour is to keep retrying on the configured refresh schedule. Retrying more aggressively — for instance, on every recomposition — risks invalid-traffic flags. ## Where to next? [Section titled “Where to next?”](#where-to-next) [Native ads](/formats/native/)Ads that match your own layout. [Caching, retry and timeouts](/advanced/caching-retry-timeouts/)Retry backoff and load bounds. [Revenue and paid events](/advanced/revenue-events/)AdValue and the mediation chain. [Troubleshooting](/reference/troubleshooting/)Blank banners and no fill.

---

# Interstitial ads

> Compose Multiplatform interstitial ads with suspend load and show, multi-ad caching, TTL eviction, retry, and why a second show returns NotReady.

## How do I show an interstitial ad in Compose Multiplatform? [Section titled “How do I show an interstitial ad in Compose Multiplatform?”](#how-do-i-show-an-interstitial-ad-in-compose-multiplatform) Interstitial, rewarded, rewarded interstitial and app-open controllers all implement `FullScreenAdController`, whose surface is `load()`, `show()`, `isReady()`, `preload()`, `availability()`, `clear()`, `loadState: StateFlow<AdLoadState>`, `events: SharedFlow<AdEvent>` and `placement`. The interstitial integration: 
```kotlin
val placement = remember {
    AdPlacement(
        id = "interstitial_main",
        format = AdFormat.Interstitial,
        androidAdUnitId = TestAdIds.ANDROID_INTERSTITIAL,
        iosAdUnitId = TestAdIds.IOS_INTERSTITIAL,
    )
}
val interstitial = remember(adManager) { adManager.interstitial(placement) }
val scope = rememberCoroutineScope()


// Preload, well before the moment you want to show
scope.launch {
    when (val state = interstitial.load()) {
        is AdLoadState.Loaded -> println("ready: ${state.responseInfo?.responseId}")
        is AdLoadState.Failed -> println("load failed: ${state.error}")
        else -> Unit
    }
}


// Show — suspends until the ad is dismissed
scope.launch {
    when (val result = interstitial.show()) {
        is AdShowResult.Shown -> println("shown and dismissed")
        is AdShowResult.NotReady -> println("call load() first")
        is AdShowResult.Failed -> println("show failed: ${result.error}")
    }
}
```
 Two rules that matter. Wrap the controller lookup in `remember` because controllers are placement-keyed and cached. And call `show()` from a UI-scoped coroutine and never `GlobalScope`, because it suspends for the ad’s full on-screen lifetime. The `remember(adManager)` form (rather than `remember { … }`) is the common shape: it is keyed on the manager so the controller is rebuilt if the manager is replaced, but not on every recomposition. The placement itself is `remember`-ed separately so its id is stable across recompositions of the same screen. A typical app also owns the placement list as a `val` in a `CompositionLocal` or a top-level object so every screen shares the same `AdPlacement` instances. ## What does show() actually return? [Section titled “What does show() actually return?”](#what-does-show-actually-return) The three-case sealed result explicitly: * `AdShowResult.Shown` — the ad was presented and has now been dismissed. This is **not** “the ad started”; it is “the ad finished.” It is the only result on the success path. * `AdShowResult.NotReady` — there was nothing to show, or a presentation is already active on this controller. This is the no-op result; do not retry immediately. * `AdShowResult.Failed(error)` — the SDK started a presentation but the platform rejected it. The `AdError` carries `code`, `message`, `domain` and `responseInfo`. Branching on the result is the right shape; do not assume the ad shown just because the call returned. A `Failed` result is rare but real, usually caused by an iOS ATT denial that lands between the `show()` call and the platform’s `present` hook, or by a race with another presentation on the same controller. A practical point on `Shown`: it is emitted after the platform SDK fires its `didDismissFullScreenContent` / `onAdDismissedFullScreenContent` callback. The coroutine that called `show()` resumes at that point. A common shape is to use `Shown` as the trigger to launch the next screen, hide the loading indicator, or restore UI that was disabled during the presentation. ## What happens between load and show? [Section titled “What happens between load and show?”](#what-happens-between-load-and-show) Full-screen ad lifecycle: load, cache, show, reloadCLAUDE.md invariants #1, #2, #9[Read this diagram in words](/reference/diagrams-in-words/#full-screen-lifecycle) The state machine the diagram shows, in prose: `AdLoadState` moves `Idle → Loading → Loaded(responseInfo)` or `Failed(error)`. Loaded ads enter a TTL’d FIFO cache. `show()` consumes the oldest first. Expired entries are evicted on access. `clear()` bumps a generation counter so a load or scheduled reload started before the `clear()` can never repopulate a cache the caller just asked to be emptied. The generation counter is the part that is hard to see from the public API but matters in practice: without it, an in-flight `load()` issued before `clear()` could race with the clear and leave the cache populated when the caller expected it empty. With it, the load checks the generation before publishing its result and discards it on a mismatch. The same mechanism protects `reloadAfterShow` from re-populating a cache the caller just cleared. The [architecture reference](/reference/architecture/) has the full state machine. A subtle but important consequence: `load()` returns a single `AdLoadState`, but the cache it represents may be larger. A `Loaded` result with `responseInfo` only describes the most recent entry; `availability().cachedCount` is the source of truth for how many ads the cache currently holds. The two views are consistent — the cache never claims more than `maxSize` and never reports an expired entry — but they answer different questions. ## How do I cache more than one interstitial? [Section titled “How do I cache more than one interstitial?”](#how-do-i-cache-more-than-one-interstitial) 
```kotlin
AdPlacement(
    id = "cached_interstitial",
    format = AdFormat.Interstitial,
    adUnitIds = AdUnitIds(android = "…", ios = "…"),
    cachePolicy = AdCachePolicy(
        maxSize = 3,               // load() tops the cache up to 3 ads
        reloadAfterShow = true,    // refill in the background after each show
    ),
)
```
 Each behaviour, in turn. `load()` fills the cache sequentially and a partial fill still reports `Loaded`; the cache is full when it has `maxSize` ads. `show()` consumes FIFO, oldest first. TTL defaults are one hour for full-screen formats and four hours for app-open, both from `AdExpirationPolicy`. `preload()` is an alias of `load()` — both top up the cache and return the resulting `AdLoadState`. The [caching, retry and timeouts guide](/advanced/caching-retry-timeouts/) goes through every knob. A warning worth stating plainly: a large `maxSize` is not free. Every cached ad is a live SDK object with its own TTL, and an ad shown near the end of its hour is more likely to be an expired eviction than an impression. The default of one is right for a natural-break interstitial; a `maxSize` of three is right for a game’s end-of-level cadence; a `maxSize` of ten is almost always wrong. `reloadAfterShow = true` is the right choice for a placement that should always be ready to show. The library schedules a background reload after each `show()`, so the next break has warm inventory. The cost is the same as a regular `load()` — the next impression incurred the network cost of a request — but the timing is guaranteed, and the user never sees a “loading” state because no ad is currently being shown. ## Why does a second show() return NotReady? [Section titled “Why does a second show() return NotReady?”](#why-does-a-second-show-return-notready) `show()` is **not reentrant per controller.** Calling it again while a previous `show()` on the *same* controller is still on screen returns `AdShowResult.NotReady` immediately — it does **not** queue and wait for the first presentation to finish. Await the first `show()`’s result, which suspends until dismissal, before issuing another on the same controller. The design reason in one sentence: presentation ownership is a one-shot handle, so a queued second show would either double-present or silently swallow the caller’s request. The library surfaces the not-ready case as an explicit result rather than a thrown exception so a caller that genuinely needs to handle a denied show has a typed branch to write. A common related question: does this rule mean a controller cannot preload while another presentation is on screen? No. `load()` runs independently of `show()`. The only operation gated on the “presenting” flag is `show()` itself. The cache can fill, drain, refill, and TTL-evict while a presentation is on screen. The not-ready rule is about presentation ownership, not about cache state. ## How do I check availability before showing? [Section titled “How do I check availability before showing?”](#how-do-i-check-availability-before-showing) 
```kotlin
if (interstitial.isReady()) {
    interstitial.show()
}


val availability = interstitial.availability()
println(availability.isReady)      // Boolean
println(availability.cachedCount)  // Int
println(availability.expiresIn)    // Duration?
```
 `isReady()` is a cheap boolean check while `availability()` returns the full `AdAvailability` record. Neither is a guarantee — an ad can expire between the check and the show, which is exactly why `show()` returns a result instead of throwing. Treat both as advisory, and treat `AdShowResult` as the source of truth. `expiresIn` is a `Duration?` — `null` when the cache is empty. When the cache has one ad, it is the time until that ad expires. When the cache has multiple, it is the time until the *oldest* ad expires, because that is the next one `show()` will consume. The field is useful for telemetry — “how long before we lose warm inventory?” — but not for control flow, because the same ad can expire between reading the value and acting on it. ## Where to next? [Section titled “Where to next?”](#where-to-next) [Rewarded ads](/formats/rewarded/)Rewards, and granting them exactly once. [App-open ads](/formats/app-open/)AppOpenAdCoordinator and cooldowns. [Caching, retry and timeouts](/advanced/caching-retry-timeouts/)TTL, backoff, and load bounds. [Revenue and paid events](/advanced/revenue-events/)AdValue and response info.

---

# Native ads

> Compose Multiplatform native ads — the adLayout DSL, ad pooling, availableAds recovery, maxSize accounting, media info, and the Android video-event gap.

## What are native ads, and why does AdMob CMP support them? [Section titled “What are native ads, and why does AdMob CMP support them?”](#what-are-native-ads-and-why-does-admob-cmp-support-them) Native ads deliver ad assets — headline, body, icon, media, call to action, advertiser, star rating, price, store — without a fixed creative, so the app composes them into its own design. For a feed this is the difference between a banner-shaped ad that breaks the visual rhythm and an ad row that looks like every other row. The mechanism behind it: `adLayout { … }` is a declarative description that the SDK turns into **platform-native views** with every asset registered for click and impression tracking, rather than Compose surfaces layered over an invisible ad view. That distinction is the reason clicks and impressions are attributed correctly. A native ad that is *rendered* correctly but not *registered* correctly will appear in the app without ever being billed. Native ads are also the format with the most asymmetric support across the Kotlin Multiplatform AdMob wrapper ecosystem. Most wrappers stop at the three full-screen-plus-banner formats and treat native as a “future” feature. AdMob CMP supports native today because the publisher feed pattern is the most common reason people reach for an AdMob SDK in the first place. ## How do I render a native ad in Compose Multiplatform? [Section titled “How do I render a native ad in Compose Multiplatform?”](#how-do-i-render-a-native-ad-in-compose-multiplatform) 
```kotlin
val placement = remember {
    AdPlacement(
        id = "feed_native",
        format = AdFormat.Native,
        androidAdUnitId = TestAdIds.ANDROID_NATIVE,
        iosAdUnitId = TestAdIds.IOS_NATIVE,
        maxCacheSize = 5,
    )
}


val feedAdLayout = remember {
    adLayout {
        column(modifier = AdModifier.fillMaxWidth()) {
            media(
                modifier = AdModifier
                    .fillMaxWidth()
                    .aspectRatio(16f / 9f)
                    .clipRounded(8.dp)
            )
            spacer(modifier = AdModifier.height(8.dp))
            headline(maxLines = 2)
            body(maxLines = 3)
            row(spacing = 8.dp) {
                icon(modifier = AdModifier.size(24.dp))
                advertiser()
                adBadge()
            }
            callToAction(modifier = AdModifier.fillMaxWidth())
        }
    }
}


NativeAdView(
    placement = placement,
    itemKey = "feed_slot_1",
    layout = feedAdLayout,
    modifier = Modifier.fillMaxWidth(),
    onEvent = { event -> /* Loaded, Impression, Clicked, Paid, Video* */ },
)
```
 Two rules a reader will otherwise learn the hard way. First, `itemKey` must be **stable per slot** — it is what drives pool acquire and release, so it should identify the position in the list, not the ad. Second, the placement `id` must be static and finite: controllers are cached per id for the manager’s lifetime and are never auto-evicted, so generating `"feed_item_$index"` leaks a controller per row. For a feed, reuse one placement id and let the pool serve per-item ads. The `maxCacheSize` parameter on the placement sets the pool’s budget, not the layout’s content. It is the upper bound on available-plus-in-use ads, so a value of 5 means the feed can have at most five live ad rows at any moment. The default of 1 is rarely right for a feed; the recommended value is “the number of ad rows that can be on screen at once, plus one”, which gives the pool enough headroom to refill while the user is scrolling without inflating memory use. `NativeAdView` is a thin wrapper over the pool: it acquires on attach, releases on dispose, and re-runs the acquisition on `availableAds` changes. The pool’s accounting is what the composable enforces, so a misuse of `itemKey` (a key that changes on every recomposition, for example) shows up as a slow leak of ads rather than a crash. The [troubleshooting guide](/reference/troubleshooting/) has the symptom table. ## How does the adLayout DSL work? [Section titled “How does the adLayout DSL work?”](#how-does-the-adlayout-dsl-work) Three properties. Each `adLayout { … }` construction recursively validates the tree and computes a structural identity string, so it is not free; retain custom layouts with `remember { adLayout { … } }`, or `remember(variant) { adLayout { … } }` for dynamic variants, to avoid revalidating and rebuilding platform views on every recomposition. Nodes are **functions with named arguments** (`headline(maxLines = 2)`), not property-assignment blocks — a detail worth stating explicitly because the shape looks like Compose but is not. And every node takes an `AdModifier`, a separate modifier type from Compose’s `Modifier`, because the tree is serialised down to native views. The structural identity is the validator’s input. Two layouts that *look* identical but differ in tree shape — one inlining an `advertiser()` call where the other uses a `row { advertiser() }` — have different identity strings and are treated as different layouts. That matters for caching: the validator does not re-run when a layout’s identity string matches a previously-validated one, and the platform-side view construction can be reused. ## Which layout nodes are available? [Section titled “Which layout nodes are available?”](#which-layout-nodes-are-available) | Node | Asset | Notes | | -------------------------------------------------- | ------------------------- | ------------------------------------------------------- | | `headline()` | Headline | The only required asset | | `body()`, `advertiser()`, `price()`, `store()` | Text assets | Hidden or collapsed per `visibilityPolicy` when missing | | `starRating()` | Star rating | Text asset; no `maxLines` parameter | | `icon()` | App icon | | | `media()` | Image or video media view | Use `mediaInfo()` for the real aspect ratio | | `callToAction()` | Call-to-action button | | | `adBadge()` | The “Ad” label | Required by AdMob policy; the validator warns if absent | | `adChoices()` | AdChoices icon | | | `row()`, `column()`, `box()`, `spacer()`, `text()` | Containers and statics | `row` and `column` take a `spacing` argument | The `AdModifier` paragraph: sizing (`fillMaxWidth`, `size`, `height`, `width`, `weight`, `sizeIn`, `aspectRatio`), spacing (`padding`, `margin`), decoration (`background`, `border`, `cornerRadius`, `clipRounded`, `clipCircle`, `elevation`, `alpha`), and visibility (`visible`, `invisible`, `gone`). Two modifiers that are easy to misuse. `aspectRatio(16f / 9f)` forces a fixed ratio on the media view, which is the right choice when the ad unit is configured to serve a known creative shape and the wrong choice when the unit mixes orientations. The native media view will letterbox or pillarbox to fit, which is rarely what the app wants for a feed. The right answer for a feed is to query `mediaInfo(token).aspectRatio` and use the actual creative ratio at render time. `cornerRadius` and `clipRounded` are similar — the former is a generic value, the latter is a shape-aware alternative that maps to `CALayer.cornerRadius` on iOS and to a `Shape` drawable on Android. ## Do I have to write a custom layout? [Section titled “Do I have to write a custom layout?”](#do-i-have-to-write-a-custom-layout) No. `AdTemplates` ships four ready-made layouts: `AdTemplates.mediaCard` (the `NativeAdView` default), `AdTemplates.feedCard`, `AdTemplates.medium` and `AdTemplates.compact`. The shortest possible integration: 
```kotlin
NativeAdView(
    placement = placement,
    itemKey = "feed_slot_1",
    layout = AdTemplates.compact,
)
```
 Custom layouts are for cases where the templates do not match the app’s visual language. The DSL is small enough that a custom layout rarely takes more than a screen of code, and the validator catches the structural mistakes a custom layout is most likely to make. A note on `AdTemplates` reuse: the templates are `val`s, not factories. They can be used as-is across the whole app without revalidation, and that is the recommended pattern for the common case. A custom layout that needs to vary by feed context — a “compact” mode for one section and a “media-heavy” mode for another — is a different shape: build each variant in its own `remember { adLayout { … } }` and select the right one at the call site, rather than parameterising a single layout. ## How does the native ad pool work? [Section titled “How does the native ad pool work?”](#how-does-the-native-ad-pool-work) Native ads are single-use, so a native placement is served by a **pool** rather than a single controller. `NativeAdView` acquires and releases automatically via `itemKey`. Manual control looks like this: 
```kotlin
val pool = adManager.nativeAd(placement)


scope.launch { pool.preload(count = 5) }


val token = pool.acquire() ?: return
try {
    val info = pool.mediaInfo(token)   // aspectRatio, hasVideoContent, durationSeconds
    // render using `token`
} finally {
    pool.release(token)                // every acquired token MUST be released
}
```
 Native ad pool lifecycle and maxSize accountingCLAUDE.md invariants #3, #4, #8[Read this diagram in words](/reference/diagrams-in-words/#native-pool-lifecycle) The accounting the diagram shows: * `AdCachePolicy.maxSize` budgets **available + in-use** ads together, not just cached ones. * `release()` **destroys** the ad, because native ads are single-use. It therefore frees a `maxSize` slot **without** incrementing `availableAds`. * `clear()` drains available inventory only. Ads currently leased stay alive until their `release()`, because a live view is still rendering them. A consequence worth stating plainly: clearing a fully-leased pool frees no capacity until those views dispose. * Pooled ads expire per `AdExpirationPolicy.nativeTtl`, one hour by default, and are evicted on access. A subtle point on `requestOptions` and `nativeOptions`. The `requestOptions` parameter is the same `AdRequestOptions` shape used by every other controller — it carries custom targeting, publisher- provided ids, and category exclusions. The `nativeOptions` parameter is native-specific: it carries `AdChoicesPosition`, `MediaAspectRatio`, and `VideoOptions` for the platform SDK’s native ad options object. The two options are layered — request options apply to the network request, native options apply to the creative rendering — and neither is required. The defaults are conservative: AdChoices at top-right, media at the platform default aspect ratio, video options set by GMA. ## Why does acquire() return null, and how do I recover? [Section titled “Why does acquire() return null, and how do I recover?”](#why-does-acquire-return-null-and-how-do-i-recover) Set up the failure exactly: with `maxSize = 1` and one row holding the ad, `preload()` returns early and `acquire()` returns `null` for every other row — deterministically, not as a race. `acquire()` returning `null` used to be silent and terminal for that composition, leaving those rows blank forever. `pool.availableAds` is the signal that lets a view recover. Key the acquisition effect on it: 
```kotlin
val availableAds by pool.availableAds.collectAsState()


LaunchedEffect(pool, itemKey, availableAds) {
    pool.preload(count = 1)
    val token = pool.acquire()
    // …render, then release on dispose
}
```
 The sentence that makes it correct rather than merely plausible: **re-run `preload`, not just `acquire`.** Because `release()` destroys the ad, it frees a `maxSize` slot without incrementing `availableAds`, so an effect that only retries `acquire()` waits for a signal that will never arrive. The built-in `NativeAdView` composables already do this, which is why the manual path is the one that needs the warning. Size `maxSize` to the number of ad slots that can be **on screen at once**, plus one, not to the number of rows in the feed. A feed that scrolls infinitely and shows ad rows at intervals should size `maxSize` to “the number of ad rows the user is likely to see in a single screen” plus one. A short feed with three visible rows should size it to four. A paged carousel with one ad per page should size it to one, with `reloadAfterShow` enabled so the next page has warm inventory. The wrong size — too small — shows blank rows; the wrong size — too large — wastes memory and inflates the time-to-first-ad. ## How do I read media info and detect video? [Section titled “How do I read media info and detect video?”](#how-do-i-read-media-info-and-detect-video) 
```kotlin
val info = pool.mediaInfo(token)
if (info?.hasVideoContent == true) {
    println("video, ${info.durationSeconds}s, ratio ${info.aspectRatio}")
}
```
 `NativeMediaInfo` has exactly three fields: `aspectRatio: Float?`, `hasVideoContent: Boolean`, `durationSeconds: Double?`. The practical use is to reserve layout height from `aspectRatio` rather than hardcoding 16:9, so a portrait creative does not letterbox. `mediaInfo(token)` is the *only* way to query these fields. There is no batch query — each call hits the platform’s native-ad metadata for that specific token, and the result is stable for the lifetime of the token. A common pattern is to read `mediaInfo` once after `acquire()` and use the values to drive the layout’s measured height, so the row does not jump when the image first loads. ## Why do native video events only fire on iOS? [Section titled “Why do native video events only fire on iOS?”](#why-do-native-video-events-only-fire-on-ios) Caution **Platform gap — native video events on Android.** iOS emits five video events — `AdEvent.VideoStarted`, `VideoPlayed`, `VideoPaused`, `VideoEnded` and `VideoMuted` — via `GADVideoControllerDelegate`. The Android Google Mobile Ads Next-Gen SDK exposes no equivalent callback surface on `NativeAd`, so Android emits none. Do not rely on native video events for cross-platform logic. This is an upstream SDK gap, not an AdMob CMP omission. `mediaInfo(token).hasVideoContent` **is** cross-platform, so “does this ad have video” is answerable everywhere even though “has the video started” is not. The two answers diverge on Android: an Android native ad with video content exists, the media view plays it, but no event is emitted. Cross-platform telemetry should query `hasVideoContent` for inventory purposes and skip the video-event stream on Android. ## What does AdMob policy require of a native layout? [Section titled “What does AdMob policy require of a native layout?”](#what-does-admob-policy-require-of-a-native-layout) Three rules, all enforced by `AdLayoutValidator`: * `adBadge()` is required by AdMob policy and the validator warns when it is missing. The badge is the visual attribution the user needs to recognise the row as an ad, and its absence can invalidate a publisher’s AdMob account. * Every registered asset must stay fully inside the platform native-ad root, and ad attribution must appear at the top. The built-in templates enforce this on both platforms; custom layouts should keep the badge at the top and avoid offsets that push registered assets outside the root bounds. * On debug builds Google may display its own Native Ad Validator overlay. The overlay is informational and only shows on debug builds, so it is safe to leave enabled. How to read the validation report: 
```kotlin
val layout = remember { adLayout { /* … */ } }


LaunchedEffect(layout) {
    layout.validation.warnings.forEach { issue ->
        println("${issue.code} at ${issue.nodePath}: ${issue.message}")
    }
}
```
 `AdLayout.validation` is an `AdLayoutValidationReport` with `isValid`, `hasWarnings`, `errors` and `warnings`, and each `AdLayoutValidationIssue` carries `code`, `nodePath` and `message`. A `warning` is informational; an `error` means the layout will not behave correctly. The validator never throws — it produces a report, and the caller decides what to do with the warnings. The `nodePath` is a stable identifier for the offending node: it is the same identifier the structural identity string uses, so a report and a code change can be correlated directly. The `code` is a stable string identifier suitable for filtering — for example, a linter rule could fail CI on `ad_badge_missing` while allowing `media_placeholder_default_aspect`. ## Where to next? [Section titled “Where to next?”](#where-to-next) [Banner ads](/formats/banner/)When a fixed ad slot is the better fit. [Caching, retry and timeouts](/advanced/caching-retry-timeouts/)TTL and cache sizing for pools. [Revenue and paid events](/advanced/revenue-events/)Attributing native ad revenue. [Troubleshooting](/reference/troubleshooting/)Blank rows and null acquires.

---

# Rewarded ads

> Kotlin Multiplatform rewarded ads and rewarded interstitials — granting the reward exactly once, server-side verification, and load and show sequencing.

## How do I show a rewarded ad in Kotlin Multiplatform? [Section titled “How do I show a rewarded ad in Kotlin Multiplatform?”](#how-do-i-show-a-rewarded-ad-in-kotlin-multiplatform) `RewardedAdController` and `RewardedInterstitialAdController` both extend `FullScreenAdController` and add exactly one thing: a `show()` overload that takes a reward callback. The [interstitial guide](/formats/interstitial/) covers the shared `load` / `availability` / `clear` semantics so they are not repeated here. 
```kotlin
val placement = remember {
    AdPlacement(
        id = "rewarded_extra_life",
        format = AdFormat.Rewarded,
        androidAdUnitId = TestAdIds.ANDROID_REWARDED,
        iosAdUnitId = TestAdIds.IOS_REWARDED,
    )
}
val rewarded = remember(adManager) { adManager.rewarded(placement) }
val scope = rememberCoroutineScope()


scope.launch {
    rewarded.load()


    val result = rewarded.show(
        onRewardEarned = { reward: AdReward ->
            grantClientRewardOnce(reward.amountMicros, reward.type)
        }
    )


    when (result) {
        AdShowResult.Shown -> Unit
        AdShowResult.NotReady -> showRetryUi()
        is AdShowResult.Failed -> showAdError(result.error)
    }
}
```
 `AdReward` carries exactly two fields — `amountMicros: Long` and `type: String` — and `type` is the reward name configured in the AdMob UI. Client code should treat it as an opaque identifier to match against, not a display string. The pattern above is the right shape for a button-driven flow: preload when the user reaches the screen, show when the button is tapped. The preloaded cache is exactly the cache described on the [interstitial guide](/formats/interstitial/) — the same FIFO, the same one-hour TTL, the same generation-counter invalidation. What rewarded adds is the per-show callback and the fact that the reward grant is part of the platform SDK’s presentation lifecycle, not the consumer’s coroutine. ## When exactly is the reward earned? [Section titled “When exactly is the reward earned?”](#when-exactly-is-the-reward-earned) Four facts, because this is where money is lost: * The `onRewardEarned` callback may run **after** `show()` returns. * `AdShowResult.Shown` means presented-and-dismissed, not rewarded. * `AdEvent.RewardEarned` is also emitted on the event stream, but events are telemetry and observation. * Therefore the client must grant from exactly one place. The reward is granted inside the presentation phase the lifecycle diagram shows, before the terminal dismissal callback fires. The `onRewardEarned` callback fires inside that window, which is why awaiting `show()` alone is not enough to know whether a reward was earned. A practical note on ordering: on iOS, the platform’s `didRewardUserWithReward:` callback fires after the user has met the watch-through criterion. On Android, the equivalent callback fires inside the listener registered at load time. The library unifies both behind `onRewardEarned`, but the unified callback fires at the platform’s natural moment — which is during the ad, not after it. UI that needs to react to a reward in real time should observe the callback, not `show()`’s result. ## How do I make sure I grant the reward only once? [Section titled “How do I make sure I grant the reward only once?”](#how-do-i-make-sure-i-grant-the-reward-only-once) 
```kotlin
// Correct — one grant point
rewarded.show(onRewardEarned = { reward -> grantClientRewardOnce(reward.amountMicros, reward.type) })


// Wrong — this double-grants, because the callback already fired
LaunchedEffect(Unit) {
    adManager.events.collect { event ->
        if (event is AdEvent.RewardEarned) grantClientRewardOnce(event.reward.amountMicros, event.reward.type)
    }
}
```
 Danger Do not grant from both the callback and `AdEvent.RewardEarned`. Use the event stream for analytics only. The double-grant is the most common rewarded-ad bug, and it usually shows up in production telemetry before anyone notices it in QA. The shape of the fix is to pick one grant point — and the callback parameter on `show()` is the one the API surfaces for that purpose — and treat the event stream as a side-channel. A related anti-pattern is the “fire and forget” `load()`: a coroutine that calls `load()` and never checks the result. The result is a cache that may be empty when `show()` is called, and an interstitial-shaped surprise on the user-facing path. The [caching, retry and timeouts guide](/advanced/caching-retry-timeouts/) has the recommended preload pattern. The full surface of `RewardedAdController` is therefore: the inherited `FullScreenAdController` methods (`load`, `show`, `isReady`, `preload`, `availability`, `clear`, `loadState`, `events`, `placement`) plus the reward-callback overload of `show`. There is no separate `onRewardEarned` field on the controller, no event-listener registration, and no global “reward granted” signal. The grant point is the callback parameter, and that is deliberate. ## How do I set up server-side verification? [Section titled “How do I set up server-side verification?”](#how-do-i-set-up-server-side-verification) 
```kotlin
AdPlacement(
    id = "rewarded_extra_life",
    format = AdFormat.Rewarded,
    adUnitIds = AdUnitIds(android = "…", ios = "…"),
    fullScreenOptions = FullScreenAdOptions(
        serverSideVerification = ServerSideVerificationOptions(
            userId = "u123",
            customData = "level-7",
        ),
    ),
)
```
 The model: `userId` identifies who to credit and `customData` carries whatever context the server needs to validate the grant. AdMob calls the verification URL configured on the ad unit; that URL receives a callback with the user id, the custom data, the reward type and amount, and a cryptographic signature. For anything of real value, the server callback should be the authoritative grant while the client callback merely updates the UI optimistically. The client callback can be wrong — a user with a modified app can grant themselves a reward locally — but a server-side callback cannot, because it depends on AdMob’s signed verification. `FullScreenAdOptions` can also be passed per-call to `show()`, which is useful when the same placement serves different users or different game sessions. `customData` is opaque to AdMob — it is passed through to the verification URL untouched. The convention is to put whatever context the server needs to validate the grant: the level the user is on, the resource they were trying to buy, the campaign that triggered the offer. The library does not parse it; the server does. ## How is a rewarded interstitial different? [Section titled “How is a rewarded interstitial different?”](#how-is-a-rewarded-interstitial-different) A rewarded interstitial is a full-screen format that offers a reward without an explicit opt-in prompt from your UI. It uses the same controller interface and the same `show(onRewardEarned)` signature as a rewarded ad. The product difference is the policy: a rewarded interstitial can appear at a natural transition without a button the user has to tap, so AdMob requires an introductory screen and the format has stricter policy expectations. The one-line difference: 
```kotlin
val rewardedInterstitial = remember(adManager) {
    adManager.rewardedInterstitial(
        AdPlacement(
            id = "rewarded_interstitial_level_end",
            format = AdFormat.RewardedInterstitial,
            androidAdUnitId = TestAdIds.ANDROID_REWARDED_INTERSTITIAL,
            iosAdUnitId = TestAdIds.IOS_REWARDED_INTERSTITIAL,
        )
    )
}
```
 The mechanics — caching, retry, TTL, `show()` reentrancy — are identical to the rewarded ad. Both formats have the same load-side shape, the same show-side shape, and the same reward-callback contract. A rewarded interstitial is a placement-level decision (product and AdMob account configuration) rather than an integration-level decision, which is why the controller interface is identical. ## What does the load and show cycle look like? [Section titled “What does the load and show cycle look like?”](#what-does-the-load-and-show-cycle-look-like) Full-screen ad lifecycle: load, cache, show, reloadCLAUDE.md invariants #1, #2, #9[Read this diagram in words](/reference/diagrams-in-words/#full-screen-lifecycle) The reward callback fires inside the presentation phase the diagram shows, before the terminal dismissal. That is why awaiting `show()` alone is not enough to know whether a reward was earned: the `Shown` result lands at dismissal, which can be tens of seconds after the reward was granted, depending on ad length. A separate suspend on the reward callback, or a separate effect on the `RewardEarned` event, is the right shape for any UI that needs to react to a successful reward in real time. A reminder of the non-reentrancy rule from the [interstitial guide](/formats/interstitial/): `show()` is not reentrant per controller. A second call while the first presentation is still on screen returns `AdShowResult.NotReady` rather than queueing. Await the first result before calling again. A reward that never fires — `onRewardEarned` never called, no `RewardEarned` event on the stream — is a different shape of bug. It is almost always one of three things: the user backed out before meeting the watch-through criterion, the ad unit has no fill and `show()` returned `NotReady`, or the platform reported the ad as failed and the terminal callback was the only outcome. None of these are bugs in the library; they are the platform SDKs behaving as documented. ## Where to next? [Section titled “Where to next?”](#where-to-next) [Interstitial ads](/formats/interstitial/)The shared full-screen controller contract. [Caching, retry and timeouts](/advanced/caching-retry-timeouts/)Preloading rewarded inventory. [Revenue and paid events](/advanced/revenue-events/)Attributing rewarded revenue. [Test safety](/advanced/test-safety/)Never request live rewarded ads in debug.

---

# App Tracking Transparency

> App Tracking Transparency for Kotlin Multiplatform AdMob apps — the required Info.plist key, the consent to ATT to initialize order, and what IDFA loss costs.

## What is App Tracking Transparency and why does it matter for ads? [Section titled “What is App Tracking Transparency and why does it matter for ads?”](#what-is-app-tracking-transparency-and-why-does-it-matter-for-ads) Since iOS 14.5, an app must ask permission before accessing the IDFA, and AdMob uses the IDFA for personalised ads and attribution. Without the prompt, iOS withholds the IDFA and every request serves non-personalised ads at materially lower eCPM. The AdMob CMP library does not decide this for the app — it exposes `adManager.tracking` and leaves the timing to the caller, because the timing is the whole problem. ATT is the only place where the *order* of three otherwise unrelated calls determines whether the publisher gets paid for the ad. The consent form has to be presented, the ATT prompt has to be answered, and the first ad request has to be sent. Reversed or skipped, the user is forever non-personalised on that install. A useful framing: the three calls are the publisher’s three permissions, and iOS is the only platform that requires all of them in a specific order. Android’s equivalent is the AD\_ID permission at install time, which is automatic and unguarded. iOS chose to make the same permission a runtime prompt; the result is that the prompt’s *moment* is the publisher’s decision, and the moment is the entire constraint. A common mistake: bundling the ATT prompt with the consent form into a single onboarding screen. The consent form is presented by the platform SDK and is modal; the ATT prompt is presented by iOS and is also modal. Showing one on top of the other confuses the user about which decision they are making and is rejected by App Review. The right shape is two distinct moments, each with its own screen and its own rationale, in the order documented above. ## What is the correct call order? [Section titled “What is the correct call order?”](#what-is-the-correct-call-order) The order first, then the why: 
```kotlin
adManager.consent.gatherConsent(config)
adManager.tracking.requestAuthorization()
adManager.initialize(config, ConsentMode.InitializeOnlyIfAlreadyAllowed)
```
 Initialization order: UMP consent, then ATT, then initializeThe required call order on iOS — gather UMP consent, request App Tracking Transparency authorisation, then initialize the ads SDK — and what Android reports instead. Initialization order: UMP consent, then ATT, then initializeCLAUDE.md invariants #5, #11[Read this diagram in words](/reference/diagrams-in-words/#init-sequence) The three reasons, one sentence each. UMP consent comes first because the GDPR / TCF decision determines whether ads may be requested at all. ATT comes next because the IDFA decision must be resolved before any request goes out. And initialization comes last with `InitializeOnlyIfAlreadyAllowed` so it does not re-present a form the app has already handled. Danger Requesting ads before ATT resolves permanently forfeits the IDFA for those requests. There is no retroactive fix — those impressions are non-personalised for good. A practical note on the `ConsentMode` choice here. The `InitializeOnlyIfAlreadyAllowed` mode is the right one because the app has already driven the consent flow. Using `GatherBeforeInitialize` would re-present the UMP form on subsequent `initialize` calls, which is wrong because the publisher already chose whether to drive the flow. The pattern above is the right one for any iOS app that wants explicit control over the prompt order. ## What do I need in Info.plist? [Section titled “What do I need in Info.plist?”](#what-do-i-need-in-infoplist) 
```xml
<key>NSUserTrackingUsageDescription</key>
<string>This identifier will be used to deliver personalised ads to you.</string>
```
 This goes in the **app target’s** `Info.plist`. The string is shown verbatim in the system prompt so it should say what the user gets rather than what the app wants; App Review rejects vague or misleading strings. `./gradlew :admob-cmp-core:doctorIos` checks `GADApplicationIdentifier` and `SKAdNetworkItems` but the tracking description is the developer’s responsibility to add. The [iOS setup guide](/start/ios-setup/) has the rest of the iOS configuration. ## How do I read the tracking authorization state? [Section titled “How do I read the tracking authorization state?”](#how-do-i-read-the-tracking-authorization-state) 
```kotlin
when (adManager.tracking.status()) {
    AdTrackingAuthorization.Authorized -> Unit      // IDFA available
    AdTrackingAuthorization.Denied -> Unit          // user said no
    AdTrackingAuthorization.NotDetermined -> Unit   // prompt not shown yet
    AdTrackingAuthorization.Restricted -> Unit      // blocked by policy or parental controls
    AdTrackingAuthorization.NotApplicable -> Unit   // Android, always
}
```
 `status()` is synchronous and cheap, so it is safe to read in a settings screen. `requestAuthorization()` is suspending and presents the system prompt at most once per install — a second call returns the existing decision rather than re-prompting, which is an OS behaviour rather than a library one. The `Restricted` value is distinct from `Denied`: it is set by parental controls or device-management policy, and the user has not been given the choice to decline. A practical detail: `status()` does not present UI, so it is safe to call in a `LaunchedEffect` or a composable’s render path. Some apps gate the first ad call on a `status() != NotDetermined` check, which is a way to enforce “never show a request before the user has answered”. That check is a stronger form of the order rule on the previous section: it is enforced at the call site, not just by the library’s init flow. ## Can I request ATT from an initialization hook? [Section titled “Can I request ATT from an initialization hook?”](#can-i-request-att-from-an-initialization-hook) For apps that prefer a single `gatherConsentAndInitialize` call: 
```kotlin
AdConfig(
    androidAppId = "ca-app-pub-…",
    iosAppId = "ca-app-pub-…",
    initializationHooks = listOf(
        object : AdInitializationHook {
            override suspend fun onPhase(phase: AdInitializationPhase, config: AdConfig) {
                if (phase == AdInitializationPhase.BeforeMobileAdsInitialize) {
                    adManager.tracking.requestAuthorization()
                }
            }
        }
    ),
)
```
 `AdInitializationPhase` has exactly three values — `BeforeConsentRequest`, `BeforeMobileAdsInitialize` and `AfterMobileAdsInitialize` — and `BeforeMobileAdsInitialize` runs after the UMP gate and before native GMA initialization, which is precisely the ATT slot. Hooks run exactly once per real native-initialization attempt, so cancelling one `initialize()` caller can never skip or duplicate a hook. A note on the hook shape: the body is suspending, so it can call `requestAuthorization()` directly without `launch`. The hook itself runs inside the library’s internal `nativeInitializationScope`, which is a detached scope that survives caller cancellation. That is the design property that makes hooks safe to put critical side-effects in: even if the caller that triggered `initialize` cancels its coroutine, the hook runs to completion. A second design property worth knowing: hooks run exactly once per real native-init attempt, not once per `initialize` call. A second `initialize` call with the same effective `AdConfig` identity does not re-run hooks; it just returns the cached result. That is the property that makes hooks safe to use for network-dependent side-effects — a re-run would otherwise mean a second ATT prompt and a second network round-trip. ## What does Android do? [Section titled “What does Android do?”](#what-does-android-do) One short paragraph. Android has no ATT. `adManager.tracking` is a no-op there and always reports `AdTrackingAuthorization.NotApplicable`, so the same common-code sequence compiles and runs correctly on both platforms with no `expect`/`actual` needed. The `requestAuthorization()` call is suspending on iOS and resolves immediately on Android, which means hooks that include ATT do not introduce a measurable delay on Android. A related Android point: Android 13 and above have a similar notification-permission flow, but it is not coupled to ad attribution in the same way. The [Android setup guide](/start/android-setup/) covers the AD\_ID permission, which is the Android side of the same disclosure. ## Where to next? [Section titled “Where to next?”](#where-to-next) [iOS setup](/start/ios-setup/)SPM packages, Info.plist, and doctorIos. [UMP consent](/privacy/consent/)Consent modes and canRequestAds. [Play Data safety](/privacy/play-data-safety/)The Android side of the same disclosure. [Revenue and paid events](/advanced/revenue-events/)Measuring what IDFA loss costs you.

---

# UMP consent

> AdMob consent on Kotlin Multiplatform — UMP consent modes, canRequestAds, the privacy options form, debug geography, and resetting consent in development.

## How does UMP consent work in AdMob CMP? [Section titled “How does UMP consent work in AdMob CMP?”](#how-does-ump-consent-work-in-admob-cmp) Consent is integrated into initialization rather than bolted beside it, which makes requesting ads before consent impossible by construction. The User Messaging Platform SDK is what presents the consent form on both platforms, but the orchestration — gather consent, present the form if required, then start Mobile Ads — is the library’s responsibility. The result is a single `gatherConsentAndInitialize` call that handles the whole flow. The “impossible by construction” point matters. A naive integration that runs `MobileAds.initialize()` and then calls `requestConsentInfoUpdate` admits a window of time during which ad requests are sent to a user who has not been asked for consent. The window is short, but it exists, and AdMob’s policy treats any request to a user who has not been prompted as a violation. The library’s init order closes the window by design. 
```kotlin
adManager.gatherConsentAndInitialize(
    AdConfig(
        androidAppId = "ca-app-pub-…",
        iosAppId = "ca-app-pub-…",
    )
)
```
 Consent decision tree: canRequestAds and the privacy-options buttonWhat gates ad requests (canRequestAds) versus what gates the privacy-options button (privacyOptionsRequirementStatus), and why ConsentStatus.Obtained gates neither. Consent decision tree: canRequestAds and the privacy-options buttonCLAUDE.md invariants #5[Read this diagram in words](/reference/diagrams-in-words/#consent-decision-tree) `ConsentStatus` is a sealed interface with five cases: | `ConsentStatus` | Meaning | | --------------- | ------------------------------------------------------------------- | | `Unknown` | Not determined yet. | | `Required` | A form must be shown. | | `Obtained` | The user answered — which does not necessarily mean they consented. | | `NotRequired` | The regulation does not apply to this user. | | `Failed(error)` | The consent-info update failed; the error is attached. | A practical note on `Failed(error)`: the error is a regular `AdError` carrying the same fields as load errors — `code`, `message`, `domain`, `responseInfo`. The most common cause is a network failure on the consent-info update endpoint, which is a transient condition and can be retried. A persistent `Failed` state usually points at a misconfigured AdMob account id. ## Which ConsentMode should I use? [Section titled “Which ConsentMode should I use?”](#which-consentmode-should-i-use) 
```kotlin
adManager.initialize(config, ConsentMode.GatherBeforeInitialize)
```
 | `ConsentMode` | Behaviour | | -------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `GatherBeforeInitialize` | Request consent info, present the UMP form if required, then initialize. Recommended. | | `InitializeOnlyIfAlreadyAllowed` | No form. Initialize only if consent already permits requests; otherwise the status becomes `ConsentRequired`. | | `SkipConsent` | Bypass UMP entirely. | `gatherConsentAndInitialize(config)` is `GatherBeforeInitialize` with the ergonomics of a single call and is the right default. Use `InitializeOnlyIfAlreadyAllowed` when the app drives the consent flow itself — for instance to sequence App Tracking Transparency between consent and initialization on iOS. Do **not** substitute `SkipConsent` there, because it ignores future UMP revocation. `SkipConsent` is for apps that genuinely have no UMP obligation. The three modes exist because the consent flow has three realistic shapes. Apps that present the UMP form as their only consent UI use `GatherBeforeInitialize`. Apps that have their own consent flow (a settings screen, a TCF v2 string built outside the platform) and need the platform only as a fallback use `InitializeOnlyIfAlreadyAllowed`. Apps that have no GDPR obligation at all (region-locked apps, B2B apps with no consumer-facing traffic) use `SkipConsent`. The wrong mode is almost always `SkipConsent` chosen for convenience rather than compliance. ## What is canRequestAds and why does it gate everything? [Section titled “What is canRequestAds and why does it gate everything?”](#what-is-canrequestads-and-why-does-it-gate-everything) 
```kotlin
val consentStatus by adManager.consent.status.collectAsState()
val canRequestAds by adManager.consent.canRequestAds.collectAsState()
```
 The rule once and clearly: `canRequestAds` is the gate that matters. The SDK refuses ad requests with `AdErrorCode.CONSENT_REQUIRED` until it is `true`, unless the mode is `SkipConsent`. Before initialization succeeds, loads fail fast with `AdErrorCode.SDK_NOT_READY`. In both cases **nothing reaches the network** — a failed load here is the gate working, not a bug. The [troubleshooting guide](/reference/troubleshooting/) has the full symptom table. The point most apps get wrong: `ConsentStatus.Obtained` means the user answered the form, not that they said yes. Branch on `canRequestAds`, never on `Obtained`. A second point: `canRequestAds` is a derived state, not an input. It is the AND of “UMP says the user has made a choice”, “the choice is on the allow list for ad requests”, and “no publisher- side block is in effect”. The first two are UMP’s; the third is yours. If you set `AdConfig.skipConsent = true` but you also want to gate requests on a publisher-side flag, do not gate on `canRequestAds` because the skip bypasses UMP’s contribution to it. Gate on your own flag and use `canRequestAds` as a secondary check. ## When should I show a Privacy Settings button? [Section titled “When should I show a Privacy Settings button?”](#when-should-i-show-a-privacy-settings-button) 
```kotlin
val privacyRequirement by adManager.consent.privacyOptionsRequirementStatus.collectAsState()


if (privacyRequirement == PrivacyOptionsRequirementStatus.Required) {
    Button(onClick = { scope.launch { adManager.consent.showPrivacyOptions() } }) {
        Text("Privacy Settings")
    }
}
```
 This is the GDPR re-consent affordance. `PrivacyOptionsRequirementStatus` is `Unknown`, `Required` or `NotRequired`, and `showPrivacyOptions()` returns a `Boolean` indicating whether the form was presented. Caution Do **not** gate this button on `ConsentStatus.Obtained`. Users who declined consent still must be able to reopen the form, and gating on `Obtained` hides the entry point from exactly the users who need it. A related point on `showPrivacyOptions()`: the call is suspending and may show the form synchronously or fall through to a no-op return when the user has nothing to manage. The boolean return distinguishes the two, so a settings screen that wants to confirm “the form was shown” can branch on it; most code paths simply ignore the return value. The `Required` value of `PrivacyOptionsRequirementStatus` is what drives the GDPR’s “the user must always be able to revisit their choice” rule. UMP exposes it as a status, and the library exposes it on the consent object. Showing the button only when the status is `Required` keeps the UI consistent with the platform’s expectation: the button does not appear when there is nothing to manage, and it always appears when there is. ## How do I test the EEA consent flow? [Section titled “How do I test the EEA consent flow?”](#how-do-i-test-the-eea-consent-flow) This section must correct a real ambiguity in the API surface. The convenience `AdConfig(androidAppId = …, iosAppId = …, testDeviceIds = …)` constructor routes `testDeviceIds` into `GlobalRequestConfiguration.testDeviceIds`, which registers **GMA test devices** — the thing that makes Google serve test ads. **UMP consent-form test devices are a different field**: `AdDebugOptions.consentTestDeviceIds`. To force the EEA flow on a physical device, use the primary constructor: 
```kotlin
adManager.gatherConsentAndInitialize(
    AdConfig(
        appIds = AdAppIds(android = "ca-app-pub-…", ios = "ca-app-pub-…"),
        debugOptions = AdDebugOptions(
            testMode = true,
            consentDebugGeography = ConsentDebugGeography.Eea,
            consentTestDeviceIds = listOf("YOUR-DEVICE-HASH"),
        ),
        globalRequestConfiguration = GlobalRequestConfiguration(
            testDeviceIds = listOf("YOUR-DEVICE-HASH"),
        ),
    )
)
```
 `ConsentDebugGeography` is `Disabled`, `Eea` or `NotEea`; debug settings apply only when `testMode = true`; and the device hash is printed to logcat or the Xcode console on the first unregistered request. The [test safety guide](/advanced/test-safety/) covers the full `testMode` versus `strictTestMode` distinction. A practical note on the device hash: it is the SHA-1 of a device-derived seed, not the advertising ID. The hash is stable for the lifetime of the device’s local data and rotates when the user resets the device. It is safe to log in development because the hash cannot be reversed to the device; do not, however, ship a list of hashes to a third party. ## How do I reset consent during development? [Section titled “How do I reset consent during development?”](#how-do-i-reset-consent-during-development) 
```kotlin
scope.launch { adManager.consent.resetConsentForDebug() }
```
 `resetConsentForDebug` is a debug-only escape hatch that wipes the cached consent decision and re-prompts on the next gather. The method is named for what it is: it exists for development and should never be called from production code. The [test safety guide](/advanced/test-safety/) covers the full set of debug-only APIs. ## How do I refresh consent state without showing a form? [Section titled “How do I refresh consent state without showing a form?”](#how-do-i-refresh-consent-state-without-showing-a-form) 
```kotlin
scope.launch { adManager.consent.requestConsentInfoUpdate(config) }
```
 `requestConsentInfoUpdate` updates `status`, `canRequestAds` and `privacyOptionsRequirementStatus` without presenting a form, which is what a settings screen should call on open. `gatherConsent(config)` is the variant that *may* present the form. The two are distinguished by what the caller is willing to interrupt the user with. A common related pattern: a “Manage privacy” entry in the settings menu that calls `requestConsentInfoUpdate` on open, then reads `privacyOptionsRequirementStatus` to decide whether to show the “Privacy Settings” button. That keeps the settings screen non-blocking and lets the button only appear when there is something to manage. The `requestConsentInfoUpdate` call is suspending and returns once the platform SDK has finished its update. It does not present UI, so it is safe to call from a screen’s `LaunchedEffect` without worrying about interrupting the user. The cost is a single network round-trip to the consent-info endpoint, which is cheap enough for a settings-screen-on-open pattern but too expensive for a per-frame pattern. ## Where to next? [Section titled “Where to next?”](#where-to-next) [App Tracking Transparency](/privacy/app-tracking-transparency/)The iOS consent, ATT, initialize order. [Play Data safety](/privacy/play-data-safety/)What to declare in the Play Console. [Test safety](/advanced/test-safety/)testMode versus strictTestMode. [Troubleshooting](/reference/troubleshooting/)CONSENT\_REQUIRED and SDK\_NOT\_READY.

---

# Play Data safety

> The AdMob Play Data safety and AD_ID declaration — which data categories the Google Mobile Ads SDK collects, and what to tick in the Play Console form.

## Why does adding AdMob change my Data safety form? [Section titled “Why does adding AdMob change my Data safety form?”](#why-does-adding-admob-change-my-data-safety-form) This page explains what the SDK does so the form can be filled in accurately. It is not legal advice, and the app’s own data collection must be declared alongside the SDK’s. The categories below cover the Google Mobile Ads SDK in its default configuration; changes in GMA release notes can change the collection behaviour, and the canonical source is Google’s per-SDK data-disclosure guide for the current version. `admob-cmp` itself declares only the `INTERNET` permission. Every data category below is collected by the Google Mobile Ads SDK through transitive dependencies, and removing the library would remove the API surface but not the data collection, which is driven by GMA directly. ## Which data categories does the Google Mobile Ads SDK collect? [Section titled “Which data categories does the Google Mobile Ads SDK collect?”](#which-data-categories-does-the-google-mobile-ads-sdk-collect) The Play form asks for data type, category, and purpose. Each row in this list maps to a row in the form: | Data type | Play category | Purpose | | ------------------------------- | ------------------------------- | ----------------------------------- | | Advertising ID | Device or other IDs | Advertising or marketing | | Ad impressions and clicks | App activity → App interactions | Advertising or marketing, analytics | | Coarse location derived from IP | Location → Approximate location | Advertising or marketing | All three should be declared as **collected and shared with third parties**, because ad serving sends the data to Google and, when mediation is enabled, to the mediated networks. The [mediation guide](/advanced/mediation/) has the implications of enabling mediation for the Data safety form. A short note on what is *not* in the default collection. GMA does not collect precise location by default; the location it derives from IP is coarse. It does not collect the user’s name, email, or phone number, and it does not collect contacts, photos, or audio. Apps that add any of these via custom request options or mediation need to declare them in addition to the three rows above. ## What is the AD\_ID permission? [Section titled “What is the AD\_ID permission?”](#what-is-the-ad_id-permission) The Google Mobile Ads SDK merges `com.google.android.gms.permission.AD_ID` into the app’s manifest. Apps targeting API 33 or above that do not declare it cannot access the advertising ID, which reduces ad revenue. The permission is opt-in by default; opting out is a deliberate choice. To opt out, remove the permission explicitly: 
```xml
<uses-permission
    android:name="com.google.android.gms.permission.AD_ID"
    tools:node="remove" />
```
 State plainly: this reduces ad revenue and is not recommended unless the app is child-directed or there is another compliance reason. If the permission is removed, the Data safety declaration should reflect that the advertising ID is no longer collected — but ad impressions and coarse location still are. 
```kotlin
AdConfig(
    androidAppId = "ca-app-pub-…",
    iosAppId = "ca-app-pub-…",
    consentTagForUnderAgeOfConsent = true,                 // UMP consent-flow setting
    ageRestrictedTreatment = AgeRestrictedTreatment.Child, // GMA ad-request setting
)
```
 `AgeRestrictedTreatment` is `Unspecified`, `Child` or `Teen`, and `Teen` should be used only when the app has determined that treatment is appropriate. The two flags are independent because they govern different layers of the stack: UMP consent for GDPR-style flows, GMA for the ad request itself. A child-directed app that has only set the UMP flag has still sent ad requests without the GMA child-treatment hint, which the SDK silently ignores for non-child configurations. ## Can I opt out of the advertising ID? [Section titled “Can I opt out of the advertising ID?”](#can-i-opt-out-of-the-advertising-id) The opt-out is the manifest removal above. Its cost is the reduction in ad revenue, because Google’s bidding depends on the advertising ID for cross-app personalisation. An app that removes the ID sees the same fill rate but materially lower eCPM, because personalised bids are worth more than the non-personalised floor. For a child-directed app, the trade-off is correct. For an app that is not child-directed and has no other compliance reason, the trade-off is rarely worth it. The [Android setup guide](/start/android-setup/) has the manifest mechanics. ## What changes when I enable mediation? [Section titled “What changes when I enable mediation?”](#what-changes-when-i-enable-mediation) Each mediated network is its own SDK with its own collection behaviour, so enabling mediation can add data categories the base declaration does not cover. Every adapter’s data-disclosure documentation must be checked and the form updated. The [mediation guide](/advanced/mediation/) has the integration mechanics; the data-disclosure check is the publisher’s responsibility and changes per network. A common concrete example: enabling Meta’s Audience Network adapter adds `User ID` and `Device ID` collection under the “Social Media” and “Device or other IDs” categories, both as shared with Meta. Enabling the Pangle adapter adds similar fields under Bytedance. The full list is documented per adapter, and the publisher is responsible for re-declaring when adapters change. The form’s “shared with third parties” flag deserves more attention than it usually gets. Every ad request your app sends is shared with Google at minimum, because Google’s network is the auction host. Mediation extends that sharing list to every mediated network whose adapter you have installed and whose waterfall is configured. The “shared” flag is a yes/no answer, but the answer is “yes” for any app that has AdMob at all, and the form text is what tells the reviewer which networks are involved. A vague “shared with ad partners” is correct in spirit but rejected by reviewers who want specifics; a named list of networks is what the form is asking for. ## Where to next? [Section titled “Where to next?”](#where-to-next) [Android setup](/start/android-setup/)Manifest and the AD\_ID permission. [UMP consent](/privacy/consent/)The EU consent obligation. [Mediation](/advanced/mediation/)Extra SDKs, extra disclosures.

---

# Architecture

> The Compose Multiplatform AdMob architecture behind AdMob CMP — one shared state machine, two thin platform adapters, bindings-only iOS, and the event flow.

## How is AdMob CMP put together? [Section titled “How is AdMob CMP put together?”](#how-is-admob-cmp-put-together) Module map: one shared core, two thin platform adaptersCLAUDE.md invariants #1, #7[Read this diagram in words](/reference/diagrams-in-words/#module-map) | Package | Contents | | -------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `dev.avinya.ads` | Public API: `AdManager`, the controllers, `AdPlacement`, `AdConfig`, events, errors, consent, diagnostics | | `dev.avinya.ads.internal` | `FullScreenSlotCore` — the shared load/show/cache state machine — and `AdRetry`, capped exponential backoff | | `dev.avinya.ads.appopen` | `AppOpenAdCoordinator` plus the expected foreground signal | | `dev.avinya.ads.nativead` | The `NativeAdPool` contract, options, and media info | | `dev.avinya.ads.nativead.layout` | The `adLayout` DSL, `AdLayoutValidator`, and `AdTemplates` | | `dev.avinya.ads.ui` | The expected composables `BannerAdView` and `NativeAdView` | The platform side in prose: `androidMain` provides `AndroidGoogleAdManager` with slots, pool and banner over the GMA Next-Gen SDK, the `AdMob.manager(context)` singleton, and a `ProcessLifecycleOwner` foreground signal. `iosMain` provides `IosGoogleAdManager` over cinterop bindings, a Kotlin UIKit native-ad renderer, and an `NSNotificationCenter` foreground signal. The published module split for readers who look at Maven: `dev.avinya.ads:admob-cmp` is the umbrella artifact; `admob-cmp-core` holds the engine and `admob-cmp-compose` the Compose surface, so the controller API can be used without Compose. The split’s design rationale: a server-side app, a CL tool, or a test harness that wants the controllers but not Compose Multiplatform depends on `admob-cmp-core` directly and skips `admob-cmp-compose` entirely. The umbrella coordinate exists for the common case, not to force Compose on consumers who do not want it. ## What lives in common code, and what is platform-specific? [Section titled “What lives in common code, and what is platform-specific?”](#what-lives-in-common-code-and-what-is-platform-specific) The invariant that gives the library its shape: **one state machine, two thin platform adapters.** Every full-screen slot extends `FullScreenSlotCore`, which owns the load mutex, the TTL’d FIFO cache bounded by `AdCachePolicy.maxSize`, retry, consent gating, event emission and `reloadAfterShow`. Platform classes implement only `loadAd`, `presentAd`, `destroyAd` and `canPresent`. Why this matters to a consumer rather than only to a maintainer: it is the reason interstitial, rewarded, rewarded interstitial and app-open behave identically across platforms, and the reason a bug fixed in caching is fixed everywhere at once. The same pattern applies to native ads through the pool, and to banners through the headless-controller path. A single cache invalidation bug, once found, is fixed in common code and ships to all formats. The pattern is also the reason format-specific behaviour stays format-specific. A platform’s `loadAd` is free to call `placementId` differently from a banner’s, because the shared core does not know about per-format custom targeting. The shared core owns lifecycle, the platform adapter owns the SDK call, and the call site owns the format. ## Why does iOS ship bindings instead of binaries? [Section titled “Why does iOS ship bindings instead of binaries?”](#why-does-ios-ship-bindings-instead-of-binaries) The iOS implementation compiles against the official GMA and UMP XCFrameworks via Kotlin/Native **cinterop**. The `dev.avinya.ads.admob-cmp` Gradle plugin downloads the zips into `build/admob-cmp-ios-frameworks/` — a version-stamped cache — purely for headers. The published klib contains **bindings**, never Google’s binaries. The consuming app links GMA and UMP itself via Swift Package Manager. Then the alternatives and why each was rejected, stated as engineering trade-offs: * A CocoaPods plugin — the ecosystem and this repository are SPM-based. * Embedding binaries with `staticLibraries` — breaks mediation adapters with duplicate Objective-C classes, pins the GMA version for every consumer, and raises redistribution-licence questions. Evaluated and rejected. The accepted costs, stated without spin: consumers must add two SPM packages, and the bound GMA major version must match the SPM-resolved one. The [iOS setup guide](/start/ios-setup/) has the executable steps; the [roadmap](/project/roadmap/) explains where this distribution model goes next. A note on `staticLibraries` specifically. The Kotlin/Native cinterop system supports embedding the linked binary into the consumer’s framework via `staticLibraries` in the `.def` file. The library deliberately does not use this. The Android counterpart would be `implementation(files("…/GoogleMobileAds.aar"))` in the consumer’s build. Both shapes break mediation because the embedded GMA is a different copy from the adapter’s GMA, and the JVM and Objective-C runtimes resolve the “GMA” class non-deterministically when two copies exist in the same process. ## How does the full-screen state machine work? [Section titled “How does the full-screen state machine work?”](#how-does-the-full-screen-state-machine-work) The cache carries a generation counter, bumped by `clear()`. A load or scheduled reload started before a `clear()` checks its required generation before publishing results, so it can never repopulate a cache the caller just asked to be emptied. Presentation ownership is a one-shot handle: the core owns it until the platform slot hands it off to the SDK’s callbacks immediately before the actual show call; from then on only the SDK’s terminal callback, or a cancellation that raced in *before* hand-off, may close it. Two consequences observable from the public API: `show()` is not reentrant per controller — a second call while one presentation is active returns `AdShowResult.NotReady` rather than queueing — and cancelling a caller never decrements the process-wide presence signal once hand-off has happened, so `AppOpenAdCoordinator` never sees “not presenting” while an ad the SDK still owns is on screen. ## What is the threading model? [Section titled “What is the threading model?”](#what-is-the-threading-model) All GMA and UMP calls are wrapped in `Dispatchers.Main.immediate` internally, so every public API is main-safe and callable from any dispatcher. Registries are lock-protected. On iOS, delegate objects are strongly retained by their owners for exactly the Objective-C delegate’s lifetime, because Objective-C delegates are weak references. Without that retention, a delegate set on a transient object would be deallocated before the platform SDK fires its terminal callback, and the ad would never be destroyed. The `Main.immediate` choice, not `Main`: when a call originates on the main thread, `Main.immediate` runs the work without posting to the message queue, so the call resolves synchronously on the caller’s stack. When a call originates on another dispatcher, `Main.immediate` posts as `Main` would. The behaviour is transparent to the caller but matters for latency: a `load()` called from a UI thread on an already-Ready manager returns the cached state synchronously, which is what `StateFlow.collectAsState` depends on. A related note on coroutine cancellation. Every public API is cancellable through its coroutine context. Cancelling a `load()` cancels the network request, the generation check, and the result-publication step. Cancelling a `show()` cancels the suspension — but the presentation itself, once handed off to the platform SDK, runs to completion regardless of caller cancellation. That asymmetry is deliberate: a half-presented ad is worse than a fully-presented ad the caller has stopped caring about. ## How do events flow? [Section titled “How do events flow?”](#how-do-events-flow) 
```plaintext
platform SDK callback → slot / pool / controller
    → controller.events   (per-placement SharedFlow)
    → AdManager.events    (global SharedFlow)
```
 The sealed `AdEvent` set is `Loaded`, `LoadFailed`, `ShowFailed`, `Impression`, `Clicked`, `OpenedFullScreen`, `ClosedFullScreen`, `RewardEarned`, `Paid`, and the iOS-only `Video*` family — see [Revenue and paid events](/advanced/revenue-events/) for the per-event shapes and the analytics patterns. A note on `SharedFlow` versus `Flow`. The two event surfaces are `SharedFlow<AdEvent>` rather than `Flow<AdEvent>` so multiple collectors can attach to the same controller without each collector driving its own callback chain. The platform SDK fires a callback once; the controller re-emits it to every collector. For a single-collector pattern, the behaviour is indistinguishable from a `Flow`; for a multi-collector pattern — analytics + UI state + a test harness — `SharedFlow` is what makes the cost linear in the number of events rather than linear in the number of collectors. ## What were the key design decisions? [Section titled “What were the key design decisions?”](#what-were-the-key-design-decisions) | Decision | Rationale | | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | Suspend functions and Flow instead of listener callbacks | One paradigm. `show()` suspending until dismissal collapses five callback interfaces into one call. | | Placement-keyed, long-lived controllers | The caching, retry and lifecycle layer every app otherwise rebuilds badly. | | Consent integrated into initialization | Requesting ads before consent becomes impossible by construction. | | Bindings-only iOS distribution | Mediation safety and version freedom. | | Caching in the slot layer, not the SDK preload APIs | Those APIs were beta and asymmetric across platforms at design time. | | No bundled mediation adapters | Adapters are platform binaries tied to your GMA version and your contracts. | | `explicitApi()` plus a committed ABI dump | The public surface cannot drift silently. | The ABI dump is committed at `admob-cmp-core/api/admob-cmp-core.klib.api` and the matching file for the Compose surface, and `checkKotlinAbi` runs against it in CI. The [contributing guide](/project/contributing/) has the workflow when an intentional public change is part of a release. ## Where to next? [Section titled “Where to next?”](#where-to-next) [Caching, retry and timeouts](/advanced/caching-retry-timeouts/)The policies this machinery exposes. [Compatibility](/reference/compatibility/)Versions and the cinterop klib caveat. [Contributing](/project/contributing/)Building and testing the library. [Roadmap](/project/roadmap/)Where the iOS distribution model goes next.

---

# Compatibility matrix

> AdMob CMP Kotlin version compatibility — Kotlin, Compose, Android minSdk, iOS versions each release supports, plus the cinterop klib caveat.

## Which versions does each release support? [Section titled “Which versions does each release support?”](#which-versions-does-each-release-support) Every row is a fact from `admob-cmp/README.md` and `gradle/libs.versions.toml`. The matrix is intentionally narrow: every 1.x release has been built with the same Kotlin and Compose Multiplatform versions, because the library was designed for stability across the 1.x line. A note on rows that are *not* in the table. The library has not yet shipped a 2.0.0 release. When it does, the Kotlin floor will rise — the [roadmap](/project/roadmap/) discusses the upstream gates that would force the rise. The 1.x line is expected to receive fixes for as long as the ecosystem lags the upstream conditions, which is the design that makes the Kotlin 2.3.20 floor safe to publish against. | `admob-cmp` | Kotlin | Compose Multiplatform | Android `minSdk` | iOS deployment target | | ----------- | ------ | --------------------- | ---------------- | --------------------- | | 1.1.0 | 2.3.20 | 1.11.1 | 26 | 15.0 | | 1.0.2 | 2.3.20 | 1.11.1 | 26 | 15.0 | | 1.0.1 | 2.3.20 | 1.11.1 | 26 | 15.0 | | 1.0.0 | 2.3.20 | 1.11.1 | 26 | 15.0 | | Format | Android — GMA Next-Gen, API 26+ | iOS — GMA 13.x, iOS 15+ | Notes | | --------------------- | ------------------------------- | ----------------------- | ---------------------------------------------------------------------------------- | | Banner | ✔ Supported | ✔ Supported | Anchored adaptive, inline adaptive, fixed and fluid; collapsible on both platforms | | Interstitial | ✔ Supported | ✔ Supported | TTL'd FIFO cache, 1 hour | | Rewarded | ✔ Supported | ✔ Supported | RewardEarned event | | Rewarded interstitial | ✔ Supported | ✔ Supported | Same controller shape as Rewarded | | App-open | ✔ Supported | ✔ Supported | AppOpenAdCoordinator, cooldowns, blocking; cache TTL 4 hours | | Native | ✔ Supported | ✔ Supported | adLayout DSL and pooling on both; iOS renders through UIKit | | Capability | Android | iOS | Notes | | ----------------------------------------------------------------------------------------------------- | ---------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | UMP consent and privacy-options form | ✔ Supported | ✔ Supported | canRequestAds gates every request on both platforms | | App Tracking Transparency | — Not applicable | ✔ Supported | Android has no ATT: adManager.tracking always reports AdTrackingAuthorization.NotApplicable, and the AD\_ID manifest permission governs the advertising id there instead | | Mediation adapters | ✔ Supported | ✔ Supported | No adapters are bundled; add the ones you need | | Paid and revenue events | ✔ Supported | ✔ Supported | AdEvent.Paid carries AdValue and response info | | Native video events | ✖ Not available | ✔ Supported — five events | iOS emits VideoStarted, VideoPlayed, VideoPaused, VideoEnded and VideoMuted through GADVideoControllerDelegate. The Android GMA Next-Gen SDK exposes no equivalent callback surface on NativeAd, so Android emits none. This is an upstream SDK gap, not an admob-cmp omission — do not rely on native video events for cross-platform logic. | | immersiveMode, customClickGesture, publisherProvidedId, categoryExclusions, skipUninitializedAdapters | ✔ Supported | ✖ Silently ignored | Android-only request options | | customTargeting, placementId | ✔ Supported | ✔ Supported | Mapped on both platforms; placementId maps to placementID on iOS | Platform support matrix: six formats on Android and iOSCLAUDE.md invariants #11[Read this diagram in words](/reference/diagrams-in-words/#platform-matrix) Android and iOS are the supported ad targets, and a Kotlin Multiplatform project may target additional platforms — the ads API simply is not available in those source sets. The [architecture reference](/reference/architecture/) explains why desktop and web are out of scope. ## Which Kotlin version do I need, and why is it strict? [Section titled “Which Kotlin version do I need, and why is it strict?”](#which-kotlin-version-do-i-need-and-why-is-it-strict) This section must not be softened. The library is published as Kotlin/Native klibs **plus cinterop klibs**. Klibs are not binary-compatible across arbitrary Kotlin versions, so consumers must build with a compatible compiler. `admob-cmp` is compiled with **Kotlin 2.3.20**; consumers on a different Kotlin **minor** version may fail to resolve the klib. Patch versions are generally safe. Caution From the Kotlin evolution principles: “klib binaries are backwards compatible starting with Kotlin 1.9.20.” That guarantee **explicitly excludes cinterop klibs**: “The Kotlin **cinterop** klib binaries are still in Beta. Currently, we cannot give specific compatibility guarantees between different Kotlin versions for cinterop klib binaries.” `admob-cmp` publishes cinterop klibs (`admob-cmp-core-iosSimulatorArm64Cinterop-gmaMain.klib` and `…-umpMain.klib`), so the backward-compatibility rule does **not** cover them. Running a newer Kotlin than the library is “probably fine, not promised” — verify it for your Kotlin minor rather than assuming it. The two directions, explicitly. Consumers on an **older** Kotlin than the library are unsupported in every case. Consumers on a **newer** Kotlin are the supported direction for ordinary klibs but are unverified for the cinterop klibs. A practical note on how to verify. The [installation guide](/start/installation/) has the `./gradlew :shared:iosSimulatorArm64Test` command that exercises the cinterop klib path end-to-end. If the link succeeds, the consumer’s Kotlin version resolves the klib. If it fails with undefined symbols related to GMA or UMP, the resolution is unsupported. The [troubleshooting guide](/reference/troubleshooting/) has the full symptom table; the conservative wording here is the policy that the symptom table is built on. ## Do I need Compose Multiplatform? [Section titled “Do I need Compose Multiplatform?”](#do-i-need-compose-multiplatform) Compose Multiplatform is required only for the composable surface: `BannerAdView`, `NativeAdView` and `rememberAdManager`. The controller API — `AdManager`, the controllers, `AdPlacement` — has no Compose dependency. On Android outside Compose, `AdMob.manager(context)` returns the same process-wide singleton. A practical note: a project that depends on `admob-cmp-core` directly (skipping `admob-cmp-compose`) still gets the controllers, the consent API, the diagnostics, and the event streams. It does not get `BannerAdView`, `NativeAdView`, or `rememberAdManager`, because those live in the compose surface. Most production code uses both; server-side tools and CLIs use only `admob-cmp-core`. A related point: Compose Multiplatform itself requires a matching Kotlin version, and a project that uses Compose Multiplatform 1.11.1 is implicitly using Kotlin 2.3.20, because Compose Multiplatform pins its Kotlin version. The “Kotlin 2.3.20 only” floor is therefore a no-op for most projects that use the composable surface — the floor is already set by the Compose Multiplatform version they have. The floor is binding for projects that depend on `admob-cmp-core` directly without Compose, where the Kotlin version is not otherwise constrained. ## Which Google SDK versions are bound? [Section titled “Which Google SDK versions are bound?”](#which-google-sdk-versions-are-bound) | Platform | SDK | Version | How it arrives | | -------- | --------------------------- | ------------------------------------------ | ------------------------------ | | Android | Google Mobile Ads Next-Gen | 1.3.0 | Transitive Maven dependency | | Android | User Messaging Platform | 4.0.0 | Transitive, also pulled by GMA | | iOS | GoogleMobileAds | 13.7.0 headers; add the `13.x` SPM package | You add the Swift package | | iOS | GoogleUserMessagingPlatform | 3.1.0 headers; add the `3.x` SPM package | You add the Swift package | The rule that follows from bindings-only distribution: the SPM-resolved GMA **major** version must match the major these bindings were generated against. A package older than the bound headers fails to link on newly-added API symbols; the fix is to bump the SPM package. The [iOS setup guide](/start/ios-setup/) has the executable steps. A note on “newer” SPM packages. A GMA SPM package newer than the bound headers is **unsupported** rather than supported, because the library has not validated the consumer’s app against the new symbols. In practice, the failure mode is a link-time undefined symbol for an Objective-C class the new package introduces, which is the same failure mode as a too-old package — the difference is the direction. The supported range is the bound major version and any patch within it. ## Which platforms can consume the library? [Section titled “Which platforms can consume the library?”](#which-platforms-can-consume-the-library) The SDK is consumable from Kotlin Multiplatform and Gradle projects only — it compiles into the consumer’s umbrella framework. A pure-Swift iOS app cannot adopt it without a Kotlin Multiplatform shim. This is a deliberate consequence of the bindings-only distribution model: the iOS artifact has no Swift-callable surface, because cinterop generates a Kotlin-callable surface, not a Swift one. A pure-Swift consumer would need a thin Kotlin module that exposes the relevant controllers as Swift-callable functions. The shape of that module is the consumer’s choice, but the absence of one is why a greenfield SwiftUI project cannot adopt `admob-cmp` directly. The [roadmap](/project/roadmap/) discusses the long-term direction, which would make this kind of project viable. ## Where to next? [Section titled “Where to next?”](#where-to-next) [Installation](/start/installation/)Adding the dependency and the plugin. [Changelog](/reference/changelog/)What changed in each release. [Roadmap](/project/roadmap/)Why the Kotlin floor may rise in 2.0.0. [Architecture](/reference/architecture/)Why cinterop klibs exist at all.

---

# Every diagram in words

> Plain-text descriptions of every architecture diagram in the AdMob CMP documentation, for screen readers, text-only clients and AI agents.

Every diagram on this site has a text equivalent here, and each one links back to this page. Nothing on this page is a summary: it is the same information the diagram carries, written out. []() ## Module map: one shared core, two thin platform adapters [Section titled “Module map: one shared core, two thin platform adapters”](#module-map-one-shared-core-two-thin-platform-adapters) *Encodes `admob-cmp/CLAUDE.md` invariants #1, #7.* dev.avinya.ads:admob-cmp is an umbrella artifact. It holds essentially no code of its own; it exists so that a consumer adds one dependency and gets both real modules, which it re-exports with Gradle api scope: admob-cmp-core and admob-cmp-compose. admob-cmp-core has no Compose dependency. Its commonMain holds the public API — AdManager, the per-format controllers, AdPlacement, AdConfig, AdEvent, AdError, consent and diagnostics — plus the internal shared state machines in dev.avinya.ads.internal: FullScreenSlotCore, BannerCore, NativePoolCore and AdRetry. dev.avinya.ads.appopen holds AppOpenAdCoordinator; dev.avinya.ads.nativead holds the native pool contract, its options and media info. admob-cmp-compose holds everything that needs Compose: the dev.avinya.ads.ui composables BannerAdView and NativeAdView, the adLayout DSL with its validator and templates in dev.avinya.ads.nativead.layout, and the debug screen in dev.avinya.ads.debug. androidMain supplies AndroidGoogleAdManager and the Android slots, pool and banner over the GMA Next-Gen SDK on API 26 and above, the AdMob.manager(context) singleton, and a ProcessLifecycleOwner foreground signal. iosMain supplies IosGoogleAdManager and the iOS slots, pool, banner and consent over Kotlin/Native cinterop bindings against GMA 13.x on iOS 15 and above, a UIKit native-ad renderer, and an NSNotificationCenter foreground signal. The shape of the split is the whole point. Platform classes implement only loadAd, presentAd, destroyAd, canPresent and getResponseInfo for full-screen formats, and only the BannerPlatform and NativePoolPlatform interfaces for banners and native ads. Load, show, cache, retry and consent-gating logic all live in the shared core (invariants 1 and 7). Exactly three things stay platform-side by construction and must never migrate into commonMain: native batch-assembly locking, iOS delegate creation, retention and ordering, and iOS’s activeLoad and activeLoads in-flight registries. []() ## Initialization order: UMP consent, then ATT, then initialize [Section titled “Initialization order: UMP consent, then ATT, then initialize”](#initialization-order-ump-consent-then-att-then-initialize) *Encodes `admob-cmp/CLAUDE.md` invariants #5, #11.* This is the highest-value correctness trap in the library. Three calls must happen in this order, and the order is not interchangeable. Step one: adManager.consent.gatherConsent(config). This runs Google’s User Messaging Platform consent-info update and, under ConsentMode.GatherBeforeInitialize, shows the consent form where the user’s region requires one. UMP returns a ConsentStatus and sets canRequestAds, which is the gate on whether any ad may be requested at all. The gate is checked in both load() and show(), and canPresent() is re-checked at present time (invariant 5). Step two: adManager.tracking.requestAuthorization(). On iOS 14.5 and later this shows the system App Tracking Transparency prompt and resolves to Authorized, Denied, Restricted or NotDetermined. The prompt cannot appear at all unless NSUserTrackingUsageDescription is present in the app target’s Info.plist; without that key iOS silently withholds the IDFA and every request serves non-personalised ads at materially lower eCPM. Android has no ATT: adManager.tracking is a no-op there and always reports AdTrackingAuthorization.NotApplicable. Step three: adManager.initialize(config, ConsentMode.InitializeOnlyIfAlreadyAllowed). Only now does the Google Mobile Ads SDK initialize and the first ad request become possible. AdManagerStatus moves to Ready, and UI should gate on that. Why the order is load-bearing: requesting ads before ATT resolves permanently forfeits the IDFA for those requests (invariant 11). It is not a delay or a degradation that later recovers — those requests are served without the identifier for good. Consent must precede ATT in turn, because UMP is what decides whether requests are permitted at all. []() ## Full-screen ad lifecycle: load, cache, show, reload [Section titled “Full-screen ad lifecycle: load, cache, show, reload”](#full-screen-ad-lifecycle-load-cache-show-reload) *Encodes `admob-cmp/CLAUDE.md` invariants #1, #2, #9.* FullScreenSlotCore is the shared state machine behind interstitial, rewarded, rewarded-interstitial and app-open ads. A controller starts Idle. load() moves it to Loading; success moves it to Loaded and admits the ad into the cache; failure moves it to Failed, after AdRetry’s capped exponential backoff has been exhausted for retryable errors. show() presents the head of the cache. The cache is a per-slot deque of at most AdCachePolicy.maxSize entries, default 1, shown first-in-first-out, with expired entries pruned on every touch. Time-to-live comes from AdExpirationPolicy: one hour for full-screen formats, four hours for app-open. presentAd suspends until the ad is dismissed. A presented ad is destroyed on normal return only, never on cancellation — cancelling mid-show means the ad is still on screen (invariant 2). Presentation ownership is a one-shot FullScreenPresentationHandle: the core owns it until the platform slot calls tryHandOffToCallbacks() immediately before invoking the SDK’s show, and from that moment only the SDK’s terminal callback, or a cancellation that raced in before hand-off, may close it. Because of that hand-off, show() is not reentrant per controller. A second show() while a presentation is live on the same controller returns AdShowResult.NotReady immediately rather than queuing behind it. Await one show()‘s result before calling it again. After dismissal, if AdCachePolicy.reloadAfterShow is true the core schedules a reload; otherwise the controller returns to Loaded if the cache still holds an ad, or Idle if it is empty. clear() bumps a generation counter and retires the cached ads. Every load and every scheduled reload carries the generation it started with and re-checks it before publishing a result, so a load that was already in flight when clear() ran is discarded instead of repopulating a cache the caller just asked to be emptied. Every suspending operation is bounded (invariant 9). Loads run inside withTimeoutOrNull(placement.timeoutPolicy.loadTimeout) in the shared core — never per platform — and that timeout bounds the whole attempt sequence including retry backoff. Presentation bounds only the pre-hand-off window; once the SDK owns the presentation it is never force-closed. []() ## Native ad pool lifecycle and maxSize accounting [Section titled “Native ad pool lifecycle and maxSize accounting”](#native-ad-pool-lifecycle-and-maxsize-accounting) *Encodes `admob-cmp/CLAUDE.md` invariants #3, #4, #8.* The native pool serves per-item ads to a feed from a single placement id. pool.preload(count) asks the platform to run one batch load; the loaded ads enter the pool’s available inventory. pool.acquire() leases one and returns a token; NativeAdView renders it; pool.release(token) hands it back. AdCachePolicy.maxSize budgets available plus in-use ads together, and must not be redefined (invariant 8). With maxSize = 1 and one row already holding the ad, preload() returns early and acquire() returns null for every other row — deterministically, not as a race. pool.availableAds is a `StateFlow<Int>` that publishes only the available half of that budget. It is the signal that lets a view recover from a null acquire, so views key their acquisition effect on it. The subtle part: release() destroys the ad, because native ads are single-use. It therefore frees a maxSize slot without incrementing availableAds. A view must re-run preload(), not just acquire(), or the freed slot is never refilled. The bundled NativeAdView composables already do this. clear() drains and destroys available inventory only. Ads currently leased stay alive until their release(), because a live view is still rendering them, so peek(token) keeps resolving after a clear(). One consequence follows directly: clearing a fully-leased pool frees no capacity at all until those views dispose. A generation counter guards in-flight batches the same way it does for full-screen slots, so a batch completing after clear() cannot repopulate the pool. Two things stay platform-side by construction. Batch assembly is touched from two threads — the SDK callbacks on Dispatchers.Main.immediate and invokeOnCancellation from any thread — so every read and write of the pending list and the cancelled flag goes through the platform’s own lock (invariant 3). And on iOS, ObjC delegates are weak, so the platform ad handle carries strong Kotlin references to them (invariant 4); because the core retains the ad handle, the delegate is alive by construction and the core never has to know delegates exist. []() ## Banner geometry: host-supplied width to resolved adaptive size [Section titled “Banner geometry: host-supplied width to resolved adaptive size”](#banner-geometry-host-supplied-width-to-resolved-adaptive-size) *Encodes `admob-cmp/CLAUDE.md` invariants #6.* Banner controllers have no layout context, and must never acquire one. Geometry is a host-supplied input (invariant 6). The normal path: BannerAdView measures its own container and passes the measured width in as BannerGeometry(widthDp). A headless caller driving the controller directly supplies it explicitly: adManager.banner(placement).load(geometry = BannerGeometry(widthDp = 320)). BannerCore then resolves the width as geometry?.widthDp ?: platform.fallbackWidthDp(). The fallback is nullable on both platforms, deliberately, so that BannerCore — not the platform — owns the failure policy. When it resolves to null the load fails with an explicit error telling the caller to supply a width or use BannerAdView, rather than guessing one. On Android the fallback comes from the current Activity and is null when there is none. On iOS it reads the key window’s bounds, never UIScreen.mainScreen: window bounds are what is correct in Split View, Slide Over and popovers. The earlier UIScreen-based code silently produced full-screen width in those configurations, sizing every banner wrong with no error at all. With a width in hand, the core calls platform.resolveSize(sizePolicy, widthDp) to produce the platform’s own ad-size type, then loadBanner(size, sizePolicy, requestOptions, requiredGeneration). refresh() replays the whole resolved request — geometry, size policy and request options — from the most recent load, not just the resolved size. registerGeometry() records a measured width without triggering a load, which is what lets a BannerRefreshPolicy.Manual placement refresh at the right width even though it performs no automatic load. []() ## Consent decision tree: canRequestAds and the privacy-options button [Section titled “Consent decision tree: canRequestAds and the privacy-options button”](#consent-decision-tree-canrequestads-and-the-privacy-options-button) *Encodes `admob-cmp/CLAUDE.md` invariants #5.* Two independent decisions are routinely confused, and conflating them is the most common consent bug. The first decision is runtime: may an ad be requested at all? The answer is consent.canRequestAds, a `StateFlow<Boolean>` that UMP sets after a consent-info update. When it is false, the consent gate rejects the request — and it is checked in both load() and show(), with canPresent() re-checked at present time, so neither check may be removed (invariant 5). Callers see AdErrorCode.CONSENT\_REQUIRED. ConsentMode.GatherBeforeInitialize is what shows the UMP form where the region requires one and re-evaluates the gate afterwards. The second decision is user interface: should the app show a privacy-settings entry point? The answer is consent.privacyOptionsRequirementStatus == PrivacyOptionsRequirementStatus.Required, and only that. When it is Required, show the button and wire it to consent.showPrivacyOptions(). ConsentStatus.Obtained gates neither decision. It mirrors UMP’s own consent status and is distinct from canRequestAds, which can be true even when consent was never explicitly obtained — for example ConsentStatus.NotRequired outside the EEA, where no form is ever shown and ads still serve normally. Gating the privacy-options button on Obtained hides the button from exactly the users who are entitled to it. []() ## Retry timeline: capped exponential backoff [Section titled “Retry timeline: capped exponential backoff”](#retry-timeline-capped-exponential-backoff) *Encodes `admob-cmp/CLAUDE.md` invariants #9.* AdRetryPolicy defaults to maxAttempts = 2, and maxAttempts counts the initial attempt. The default therefore means one initial attempt plus at most one retry. Set maxAttempts = 1 for no retry at all. The delay before retry number n is min(initialDelay × backoffMultiplier^(n−1), maxDelay). With the defaults — initialDelay 2s, backoffMultiplier 2.0, maxDelay 30s — the delays run 2s, 4s, 8s, 16s and then flatten at 30s however many attempts are configured. Only transient failures are retried. On Android, LoadAdError.code is an enum in the GMA Next-Gen SDK, so its toString() yields the enum name, and the retryable set matches on those names: NETWORK\_ERROR, TIMEOUT and INTERNAL\_ERROR. On iOS the codes arrive as numeric strings, and the retryable set is 2 (network), 5 (timeout) and 11 (internal). No fill is never retried: NO\_FILL on Android, code 1 on iOS. It means the ad server had no inventory for this request, so retrying burns requests and depresses fill rate rather than recovering anything. Configuration failures — INVALID\_REQUEST, APP\_ID\_MISSING, INVALID\_AD\_RESPONSE — are equally permanent and equally not retried. The gates consent\_required and sdk\_not\_ready are not load failures at all and never enter the retry path. The whole sequence, backoff included, runs inside withTimeoutOrNull(placement.timeoutPolicy.loadTimeout) in the shared core (invariant 9). The timeout deliberately bounds the sequence rather than each attempt: a listener that never calls back would otherwise restart the clock on every retry and still never finish. []() ## Platform support matrix: six formats on Android and iOS [Section titled “Platform support matrix: six formats on Android and iOS”](#platform-support-matrix-six-formats-on-android-and-ios) *Encodes `admob-cmp/CLAUDE.md` invariants #11.* All six ad formats are supported on both platforms: banner (anchored adaptive, inline adaptive, fixed and fluid, including collapsible), interstitial, rewarded, rewarded interstitial, app-open and native. Android requires API 26 or later on the GMA Next-Gen SDK; iOS requires iOS 15 or later on GMA 13.x. UMP consent, the privacy-options form, mediation adapters, and paid/revenue events via AdEvent.Paid all work identically on both platforms. App Tracking Transparency is iOS-only. Android has no equivalent and adManager.tracking always reports AdTrackingAuthorization.NotApplicable; advertising-id access there is governed instead by the AD\_ID manifest permission. On iOS, ATT must be requested after UMP consent and before the first ad request (invariant 11). One genuine gap exists, and it is upstream. iOS emits five native video events — VideoStarted, VideoPlayed, VideoPaused, VideoEnded and VideoMuted — through GADVideoControllerDelegate. The Android GMA Next-Gen SDK exposes no equivalent callback surface on NativeAd, so Android emits none. This is a Google SDK gap, not an admob-cmp omission, and it means cross-platform logic must not depend on native video events. Five request options are Android-only and are silently ignored on iOS: immersiveMode, customClickGesture, publisherProvidedId, categoryExclusions and skipUninitializedAdapters. By contrast customTargeting and placementId are mapped on both platforms.

---

# Troubleshooting

> Fix AdMob errors on Kotlin Multiplatform — undefined symbols _OBJC_CLASS_$_GAD when linking iOS tests, no fill, blank banners, consent gates and crashes.

## Why do my iOS Kotlin/Native tests fail with undefined GAD symbols? [Section titled “Why do my iOS Kotlin/Native tests fail with undefined GAD symbols?”](#why-do-my-ios-kotlinnative-tests-fail-with-undefined-gad-symbols) This section must be answerable in the first screen. The exact error text a reader pasted into a search box: 
```plaintext
Undefined symbols for architecture arm64:
  "_OBJC_CLASS_$_GADMobileAds", referenced from: …
  "_OBJC_CLASS_$_GADBannerView", referenced from: …
ld: symbol(s) not found for architecture arm64
```
 The cause in two sentences, no preamble: `admob-cmp` ships cinterop **bindings** only, never Google’s binaries. An iOS app resolves `GAD*` and `UMP*` at final link from the Swift packages Xcode links — but a Kotlin/Native test executable has **no Xcode, no `.xcodeproj` and no Swift Package Manager anywhere in the picture**, so it must resolve those symbols itself. A useful mental model: the Kotlin/Native test link is a fully self-contained build that runs without any of the Apple toolchain’s higher-level conveniences. There is no `xcodebuild` to invoke SPM, no `IB` linker to bring in CocoaPods, no Swift package resolution at all. The link must resolve every Objective-C class the bindings reference, and the only way to make that happen is to put the framework on the link line directly. The `dev.avinya.ads.admob-cmp` Gradle plugin is what adds the framework directory and the `-framework` flags to the test executable’s link options. The fix, immediately: shared/build.gradle.kts 
```kotlin
plugins {
    id("dev.avinya.ads.admob-cmp") version "1.1.0"
}
```
 settings.gradle.kts 
```kotlin
pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
}
```
 
```bash
./gradlew :shared:iosSimulatorArm64Test
```
 The three clarifications that stop the reader trying the wrong things: * This happens even if none of your tests touch ads. The test binary contains the module’s whole main compilation, so any production code calling `rememberAdManager`, `NativeAdView` or the consent APIs brings those references along. * A `FakeAdManager` does not help. The requirement comes from the bindings being present in the link, not from anyone calling them. For faking ad *behaviour* in tests, the SDK ships `NoOpAdManager`. * Adding another SPM package does not help. SPM is not consulted during a Kotlin/Native test link. Danger Adding another Swift Package Manager package will **not** fix a `:linkDebugTestIos…` failure. Only the `dev.avinya.ads.admob-cmp` Gradle plugin does. The [installation guide](/start/installation/) has the full mechanism, and the [iOS setup guide](/start/ios-setup/) covers the Swift-package side of the same problem. A related, often-confused failure: `Undefined symbol: _OBJC_CLASS_$_GADMobileAds` during an Xcode *app* build, not a Kotlin/Native test link. That failure has the same symbol but a different fix: add the `GoogleMobileAds` Swift package to the Xcode project. The disambiguation is the failing Gradle task name — `linkDebugTestIosSimulatorArm64` is a Kotlin/Native test link; `xcodebuild` invoked through Gradle is an Xcode app build. The two fixes look similar (both involve frameworks) but the mechanisms are different: SPM for the Xcode build, the Gradle plugin for the test build. ## Which link failure am I actually looking at? [Section titled “Which link failure am I actually looking at?”](#which-link-failure-am-i-actually-looking-at) The same symptom text appears in two completely different builds with two completely different fixes. The disambiguation table: | Symptom | When it happens | Cause | Fix | | ------------------------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `Undefined symbol: _OBJC_CLASS_$_GAD*` | During an **Xcode / app** build | The GoogleMobileAds SPM package is not added | Add the GMA Swift package — see [iOS setup](/start/ios-setup/) | | `Undefined symbol: _OBJC_CLASS_$_UMP*` | During an **Xcode / app** build | The UMP SPM package is not added | Add the UserMessagingPlatform Swift package | | `Undefined symbol: _OBJC_CLASS_$_GAD*` or `_UMP*` | During `:linkDebugTestIos…` | A Kotlin/Native test executable cannot use SPM | Apply the `dev.avinya.ads.admob-cmp` Gradle plugin. Adding an SPM package will **not** fix this. | | `Undefined symbol: _OBJC_CLASS_$_JSContext` | Either build | JavaScriptCore is not linked; a static Kotlin framework does not autolink it | Add `-framework JavaScriptCore` to `OTHER_LDFLAGS` | | `Undefined symbol: GADCurrentOrientation…` or other new-API symbols | Either build | The GMA SPM package major is older than the bound headers | Bump the GMA Swift package to `13.x` | | `__swift_FORCE_LOAD_$_swiftCompatibility56` | During a test link | The Swift runtime compatibility shims are not on the link line | Apply the Gradle plugin; it adds the Swift compatibility library directory | How to tell which build you are in: if the failing Gradle task name starts with `link` and contains `Test`, it is the Kotlin/Native test link. A second helpful disambiguator: the symbol that fails. The `_OBJC_CLASS_$_JSContext` row is the easiest to miss because the error looks GAD-related, but JavaScriptCore is a separate Apple-provided framework that GMA depends on. The `GADCurrentOrientation…` row is the easiest to misdiagnose because the symbol’s prefix looks GMA-specific, but the cause is the GMA SPM package version, not the GMA XCFramework. The table is the single source of truth for which symbol means which fix. ## What does the Gradle plugin do to fix it? [Section titled “What does the Gradle plugin do to fix it?”](#what-does-the-gradle-plugin-do-to-fix-it) Readers trust a fix they understand. The plugin’s behaviour, exactly as implemented: * It registers `downloadGmaIos` and `downloadUmpIos`, which fetch the version-stamped GoogleMobileAds and UserMessagingPlatform XCFrameworks into `build/admob-cmp-ios-frameworks/` and verify them against a pinned SHA-256. * It makes every `link…Test…` task for `iosArm64` and `iosSimulatorArm64` depend on those downloads. * It adds linker options **to test executables only**: `-F` for each framework directory, `-framework GoogleMobileAds`, `-framework UserMessagingPlatform`, `-framework JavaScriptCore` (GMA force-loads it via `GADOMIDJSContextPool`), and `-L` for the Swift compatibility library directory under the active Xcode toolchain. * It deliberately leaves the **shipped app framework alone**. Kotlin/Native is supposed to leave those symbols undefined there, for Xcode to bind via SPM. * It registers `doctorIos`. * Off macOS it contributes no linker options, so Linux CI can still configure the build. 
```bash
./gradlew :shared:downloadGmaIos :shared:downloadUmpIos   # populate the cache explicitly
./gradlew :admob-cmp-core:doctorIos                       # report-only diagnostic
```
 A note on the cache. The XCFrameworks are downloaded once and cached in `build/admob-cmp-ios-frameworks/`, with a SHA-256 check on every subsequent download. The cache survives clean builds of the consumer’s own code but is invalidated by `./gradlew clean`. After a clean, the first test link re-downloads the frameworks; subsequent test links use the cache. The `downloadGmaIos` and `downloadUmpIos` tasks are the explicit form of the same operation, useful for warming the cache before a CI run that does not have network access mid-build. ## What do SDK\_NOT\_READY and CONSENT\_REQUIRED mean? [Section titled “What do SDK\_NOT\_READY and CONSENT\_REQUIRED mean?”](#what-do-sdk_not_ready-and-consent_required-mean) `AdErrorCode` is deliberately small — two string constants — because everything else is passed through from the platform SDK. The small surface is deliberate: the library’s two distinct gates are the only places where the library returns a typed error rather than a platform-code pass-through. Every other failure is a GMA error code in a string, and the [caching, retry and timeouts guide](/advanced/caching-retry-timeouts/) has the classification of which GMA codes are retried automatically. | Code | Constant value | Cause | Fix | | ------------------------------ | -------------------- | ----------------------------- | ----------------------------------------------------------------- | | `AdErrorCode.SDK_NOT_READY` | `"sdk_not_ready"` | `initialize` has not finished | Gate requests on `adManager.status` being `AdManagerStatus.Ready` | | `AdErrorCode.CONSENT_REQUIRED` | `"consent_required"` | UMP forbids requests | Run `gatherConsentAndInitialize`, or check `canRequestAds` | Both are **fail-fast gates**: nothing reaches the network, so seeing them is the design working rather than an outage. The [UMP consent guide](/privacy/consent/) has the full `canRequestAds` semantics and the consent flow. The numeric codes, which come straight from Google: | Platform codes | Meaning | Retried automatically? | | ------------------------------------------ | ------------------------------------------ | ---------------------------------------------------------------------------------------- | | Android `3`, iOS `1` | No fill — there was no ad for this request | No. Non-retryable by policy; retry at a later natural moment | | Android `0` and `2`, iOS `2`, `5` and `11` | Internal, network or timeout | Yes, per `AdRetryPolicy` — default `maxAttempts = 2`, the initial attempt plus one retry | `AdError` carries `code`, `message`, `domain` and `responseInfo`. `code` is either one of the two `AdErrorCode` strings or the platform’s own numeric code as a string, and `responseInfo.adNetworkResponseInfos` is the fastest way to see which mediation networks failed and why. The [caching, retry and timeouts guide](/advanced/caching-retry-timeouts/) and the [mediation guide](/advanced/mediation/) have the full shapes. ## Why does my Android app crash at startup? [Section titled “Why does my Android app crash at startup?”](#why-does-my-android-app-crash-at-startup) The Google Mobile Ads SDK crashes on launch when the manifest has no `com.google.android.gms.ads.APPLICATION_ID` meta-data entry. Add it with the AdMob **app** id (tilde separator), not an ad-unit id. The [Android setup guide](/start/android-setup/) has the manifest snippet and the rest of the Android configuration. A subtle variant of this failure: the manifest has the meta-data entry, but the value is an ad-unit id, not an app id. The two are visually similar — both start with `ca-app-pub-` — but the ad-unit id has a `/` between the segments and the app id has a `~`. The SDK’s manifest check accepts the presence of the entry, not its shape, and the crash comes from the value being rejected at first network call. The error message mentions “app id” but does not show the offending value, so the misdiagnosis is to assume the entry is missing. ## Why does my banner render nothing? [Section titled “Why does my banner render nothing?”](#why-does-my-banner-render-nothing) Four causes, one line each. The manager is not `AdManagerStatus.Ready`. The placement uses `BannerRefreshPolicy.Manual` and nothing has called `adManager.banner(placement).refresh()`. A headless `load()` was issued with no `BannerGeometry` on a platform that cannot resolve a width, which now fails rather than guessing. Or the request returned no fill. The [banner guide](/formats/banner/) has the full size-policy and refresh-policy table. ## Why does acquire() return null and leave feed rows blank? [Section titled “Why does acquire() return null and leave feed rows blank?”](#why-does-acquire-return-null-and-leave-feed-rows-blank) `AdCachePolicy.maxSize` budgets **available + in-use** ads together. With `maxSize = 1` and one row holding the ad, `preload()` returns early and `acquire()` returns `null` for every other row — deterministically, not as a race. Recover by keying the acquisition effect on `pool.availableAds` and re-running `preload`, not just `acquire`, because `release()` destroys the ad and so frees a slot without incrementing `availableAds`. The [native ads guide](/formats/native/) has the full pool accounting and the recovery pattern. ## Why does my second show() call return NotReady? [Section titled “Why does my second show() call return NotReady?”](#why-does-my-second-show-call-return-notready) `show()` is not reentrant per controller. A second call while the first presentation is still on screen returns `AdShowResult.NotReady` immediately rather than queueing. Await the first `show()`’s result — it suspends until dismissal — before calling again on the same controller. The [interstitial guide](/formats/interstitial/) has the full `FullScreenAdController` contract. A common related bug is calling `show()` on two different controllers in quick succession, expecting both to be on screen. The platform SDK presents one ad at a time per process — a second `show()` on any controller, while the first is still on screen, gets queued by the platform SDK and fires after the first dismisses. The library surfaces this as a `NotReady` return on the second controller, which is the more useful behaviour because the caller can branch on it instead of waiting for a deferred presentation. ## Why did my second initialize() call do nothing? [Section titled “Why did my second initialize() call do nothing?”](#why-did-my-second-initialize-call-do-nothing) The native Google Mobile Ads singleton initialises at most once per process. A second call with the *same* effective `AdConfig` identity — app id plus merged `GlobalRequestConfiguration` — and the same `ConsentMode` replays the first result. A call with a *different* identity is **ignored with a logged warning**, not re-applied, because GMA itself has no supported way to re-initialise with new settings. Decide the settings before the first `initialize` ever runs. The [architecture reference](/reference/architecture/) has the full singleton model. ## Why does creating a placement throw an exception? [Section titled “Why does creating a placement throw an exception?”](#why-does-creating-a-placement-throw-an-exception) `AdPlacement` validates at construction and fails closed. It throws `IllegalArgumentException` when `id` is blank, when `cachePolicy.maxSize` is below 1, or when `strictTestMode` is enabled and any ad unit id is not a Google test unit. The last one is intentional: requesting real ads from a debug build is invalid traffic, and invalid traffic gets AdMob accounts suspended. The [test safety guide](/advanced/test-safety/) has the full `testMode` versus `strictTestMode` explanation. ## Why do native video events never fire on Android? [Section titled “Why do native video events never fire on Android?”](#why-do-native-video-events-never-fire-on-android) iOS emits five video events via `GADVideoControllerDelegate`; the Android Google Mobile Ads Next-Gen SDK exposes no equivalent callback surface on `NativeAd`, so Android emits none. This is an upstream SDK gap, not an AdMob CMP omission. `mediaInfo(token).hasVideoContent` **is** cross-platform. The [native ads guide](/formats/native/) has the full explanation and the cross-platform code shape. A practical note on what this means for analytics. A publisher that wants to track “video started” events for native ads must query `mediaInfo(token).hasVideoContent` and treat every native ad as potentially-video on Android, while emitting real `VideoStarted` events on iOS. The aggregate metric is the same — “native ad with video” — but the data sources differ by platform. ## How do I diagnose the iOS setup automatically? [Section titled “How do I diagnose the iOS setup automatically?”](#how-do-i-diagnose-the-ios-setup-automatically) 
```bash
./gradlew :admob-cmp-core:doctorIos
./gradlew :admob-cmp-core:doctorIos -PadmobCmp.xcodeproj=path/to/dir
```
 It reports the XCFramework download cache state, whether the Xcode project references each SPM product, whether `Info.plist` declares `GADApplicationIdentifier` and whether that value is still Google’s sample id, and whether `SKAdNetworkItems` is present. It is diagnostic only and never fails the build. ## Where to next? [Section titled “Where to next?”](#where-to-next) [iOS setup](/start/ios-setup/)SPM packages, Info.plist, and JavaScriptCore. [Installation](/start/installation/)The Gradle plugin and test linking. [Caching, retry and timeouts](/advanced/caching-retry-timeouts/)What is retried, and what is not. [UMP consent](/privacy/consent/)Why loads fail before consent.

---

# Android setup

> Android setup for AdMob on Kotlin Multiplatform — the manifest APPLICATION_ID entry, the AD_ID permission, minSdk 26, and how to verify it works.

## What does Android need beyond the Gradle dependency? [Section titled “What does Android need beyond the Gradle dependency?”](#what-does-android-need-beyond-the-gradle-dependency) Almost nothing. The Android side of the Kotlin Multiplatform AdMob integration needs exactly one manifest entry beyond the dependency added in [Installation](/start/installation/) — the AdMob **app id**. Omitting it is not a soft failure: the Google Mobile Ads SDK crashes at startup because it cannot tell which account to attribute impressions to. iOS, by contrast, has the longer setup story with SPM, Info.plist keys, and ATT. The Android side is the shortest page on the site for a reason. The Gradle dependency itself is already on the page you came from. What Android adds is the small set of values that the GMA Next-Gen SDK cannot infer from the Kotlin code: the app id, the build configuration (`minSdk`, `compileSdk`, `targetSdk`, Android Gradle Plugin), and the repository that hosts Cronet. Each is a one-liner and none of them are the Kotlin Multiplatform library’s job. ## How do I add the AdMob app id to the manifest? [Section titled “How do I add the AdMob app id to the manifest?”](#how-do-i-add-the-admob-app-id-to-the-manifest) 
```xml
<application>
    <meta-data
        android:name="com.google.android.gms.ads.APPLICATION_ID"
        android:value="ca-app-pub-3940256099942544~3347511713" /> <!-- sample id; replace -->
</application>
```
 Three things to get right in that snippet: * This is the **app id** (`ca-app-pub-…~…`, tilde separator), not an ad-unit id (`ca-app-pub-…/…`, slash separator). The shape is the difference between GMA initialising and GMA throwing at startup. * The value shown is Google’s public sample id and must be replaced with the real id from the AdMob UI before release. * In a Kotlin Multiplatform project this entry belongs to the **Android application module’s** manifest, not the shared module. The shared module is where the Gradle dependency lives, but manifest merging happens in the app module. `admob-cmp` itself declares only `INTERNET`. Everything else below comes from the GMA and UMP transitive dependencies. The sample id in the snippet above is recognisable on sight: the `ca-app-pub-3940256099942544` publisher id is the same one Google uses across its own sample apps and the `~3347511713` suffix is the Android sample app id. The library’s `TestAdIds.ANDROID_APP_ID` constant is the same value, so a quickstart using sample ids never needs to type it. ## What is the AD\_ID permission and do I need it? [Section titled “What is the AD\_ID permission and do I need it?”](#what-is-the-ad_id-permission-and-do-i-need-it) The Google Mobile Ads SDK merges `com.google.android.gms.permission.AD_ID` into the manifest. Apps targeting API 33 or above that remove this permission cannot access the advertising ID, which reduces ad revenue. The permission comes from GMA rather than from `admob-cmp`. To opt out — for a child-directed app, for instance — remove the permission explicitly: 
```xml
<uses-permission
    android:name="com.google.android.gms.permission.AD_ID"
    tools:node="remove" />
```
 The `tools:node="remove"` directive only works when the manifest root declares `xmlns:tools="http://schemas.android.com/tools"`. Most projects already have that, but it is the kind of thing that fails silently when missing. The merged manifest in Android Studio’s “Merged Manifest” view is the fastest way to confirm the permission is gone. Caution Removing the AD\_ID permission reduces ad revenue. It is not recommended unless the app is child-directed or there is another compliance reason. Removing the permission also changes what must be declared in the Play Data safety form — see [Play Data safety](/privacy/play-data-safety/). ## What are the Android build requirements? [Section titled “What are the Android build requirements?”](#what-are-the-android-build-requirements) `admob-cmp` 1.1.0 is built and tested against these values: | Setting | Value | | ------------------------------ | -------------------------------------- | | `minSdk` | 26 | | `compileSdk` | 37 | | `targetSdk` | 36 | | Android Gradle Plugin | 9.2.1 | | Google Mobile Ads Next-Gen SDK | 1.3.0 (transitive) | | User Messaging Platform | 4.0.0 (transitive, also pulled by GMA) | One repository gotcha that trips real builds: the GMA Next-Gen SDK pulls Cronet from `org.chromium.net`, which is served by Google’s Maven repository rather than Maven Central. Without the `google()` repository declared, the build fails with a missing-artifact error that does not name the cause. settings.gradle.kts 
```kotlin
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}
```
 Add `google()` first so its resolution is preferred; the order is not strictly required but it makes the build configuration match how most AdMob projects are written. The library’s own consumer apps declare both repositories; without `google()`, the build fails on the very first Kotlin file that references GMA. ## How do I confirm Android is wired up correctly? [Section titled “How do I confirm Android is wired up correctly?”](#how-do-i-confirm-android-is-wired-up-correctly) Three short checks: * Build and install the Android app, gate the UI on `AdManagerStatus.Ready`, and confirm a banner or interstitial renders. * Outside Compose, the manager is reachable as `AdMob.manager(context)`. It is the same process-wide singleton `rememberAdManager()` returns — never construct an `AdManager` implementation directly. * If the app crashes at startup with a stack trace that does not name AdMob, the most common cause is a missing `com.google.android.gms.ads.APPLICATION_ID`. The full symptom table is on [Troubleshooting](/reference/troubleshooting/). The most common path that takes a first-time integration off the happy path is `targetSdk` and `compileSdk` drifting away from the values the library was built against. If you raise either, the transitive dependencies may pick up behaviour the library does not yet account for — particularly the GMA Next-Gen SDK’s StrictMode-sensitive code paths. The values in the table above are tested; raising them is your call and is not part of the supported compatibility window. A note on cross-platform parity: Android emits no native video events on native ads. iOS emits five (`VideoStarted`, `VideoPlayed`, `VideoPaused`, `VideoEnded`, `VideoMuted`); the Android GMA Next-Gen SDK exposes no equivalent callback surface on `NativeAd`, so cross-platform logic must not depend on them. The [native ads guide](/formats/native/) has the full explanation. ## Where to next? [Section titled “Where to next?”](#where-to-next) [iOS setup](/start/ios-setup/)SPM packages, Info.plist, ATT, and doctorIos. [Play Data safety](/privacy/play-data-safety/)What to declare in the Play Console form. [Test safety](/advanced/test-safety/)testMode versus strictTestMode. [Troubleshooting](/reference/troubleshooting/)Symptom to cause to fix.

---

# iOS setup

> iOS setup for KMP ads, ATT and IDFA — the two Swift Package Manager packages, Info.plist keys, JavaScriptCore linking, and the doctorIos check.

## Why does iOS need extra setup at all? [Section titled “Why does iOS need extra setup at all?”](#why-does-ios-need-extra-setup-at-all) The published artifact contains cinterop **bindings** only — never Google’s binaries. The app links the real GMA and UMP frameworks itself via Swift Package Manager. That buys three things: * Mediation adapters keep working because there is exactly one copy of the Objective-C classes in the process. Embedding Google’s binary in the published artifact would duplicate those classes the moment a second artifact — an adapter — is added. * GMA patch releases can be taken without waiting for this library to publish. The version floor is the bound headers, not the linked binary. * There is no redistribution question about Google’s closed-source binary. The app links it, the library does not carry it. The cost is honest: two Swift packages must be added to the Xcode project, and the SPM-resolved GMA major version must match the major this library binds. The full rationale is on [Architecture](/reference/architecture/). This is the section of the integration where the cost-benefit trade-off of the bindings-only design is most visible. A greenfield project on a fresh Mac spends about five minutes adding the two packages, three `Info.plist` keys, and the JavaScriptCore linker flag — and that is the only time the iOS side has anything the Android side does not. Once the project grows mediation adapters, that five-minute cost is what prevents the duplicate-class problem. ## Which Swift Package Manager packages do I add? [Section titled “Which Swift Package Manager packages do I add?”](#which-swift-package-manager-packages-do-i-add) 1. In Xcode, choose **File → Add Package Dependencies**. 2. Add `https://github.com/googleads/swift-package-manager-google-mobile-ads.git` and select the **GoogleMobileAds** product. Use version **13.x** — it must match the major version this library binds. 3. Add `https://github.com/googleads/swift-package-manager-google-user-messaging-platform.git` and select the **GoogleUserMessagingPlatform** product, version **3.x**. `admob-cmp` 1.1.0 binds GMA iOS 13.7.0 and UMP iOS 3.1.0 headers. A GMA SPM package older than the bound headers produces link errors on newly-added API symbols such as `GADCurrentOrientation…`; the fix is to bump the SPM package, not to downgrade the library. The same upper-bound rule applies: a GMA SPM package *newer* than 13.x is unsupported and may break the build against the bound headers. The [compatibility matrix](/reference/compatibility/) is the canonical source for which combination is supported. If the project uses Swift Package Manager’s automatic version selection (the default in recent Xcode), the `13.x` requirement is expressed as an “Up to Next Major” constraint. That gives the consumer patch releases and minor versions within the 13.x range, which is exactly the supported window. Setting it to “Exact” or “Branch” is a deliberate choice that should be revisited on every library upgrade. ## What goes in Info.plist? [Section titled “What goes in Info.plist?”](#what-goes-in-infoplist) 
```xml
<key>GADApplicationIdentifier</key>
<string>ca-app-pub-3940256099942544~1458002511</string><!-- sample id; replace -->


<key>SKAdNetworkItems</key>
<array>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>cstr6suwn9.skadnetwork</string>
    </dict>
    <!-- copy the full current list from the AdMob iOS documentation -->
</array>
```
 These go in the **app target’s** `Info.plist`. `GADApplicationIdentifier` is the app id with a tilde, not an ad-unit id; the sample id must be replaced before release. An incomplete `SKAdNetworkItems` list degrades attribution rather than breaking the build, which is why it is easy to forget and worth checking with `doctorIos`. The current `SKAdNetworkItems` list is published by Google in the AdMob iOS documentation and changes over time. The list above is a single example entry; the real list at any given release is much longer. `doctorIos` only checks for the *presence* of the key, not the completeness of the entries, so the source of truth is Google’s documentation. Apps that ship a `NSAppTransportSecurity` exception for any other reason should be aware that the AdMob iOS SDK is HTTPS-only and does not require an ATS exception of its own. Anything added in `Info.plist` for an unrelated feature does not interact with the GMA network stack. ## How do I enable App Tracking Transparency and keep the IDFA? [Section titled “How do I enable App Tracking Transparency and keep the IDFA?”](#how-do-i-enable-app-tracking-transparency-and-keep-the-idfa) The required `Info.plist` key, first: 
```xml
<key>NSUserTrackingUsageDescription</key>
<string>This identifier will be used to deliver personalised ads to you.</string>
```
 Without this key the ATT prompt cannot be shown and iOS withholds the IDFA, so every request serves non-personalised ads at materially lower eCPM. The string is shown verbatim in the system prompt so it should say what the user gets rather than what the app wants; App Review rejects vague or misleading strings. Apps that also target the European Union will combine this with a UMP consent flow. The consent form is presented by the SDK, but the order of the two prompts is up to the app, and the correct order is consent first, then ATT, then the first ad request. Reversed, you get non-personalised ads on the first sessions — sometimes for the lifetime of the install. The call order, then: 
```kotlin
adManager.consent.gatherConsent(config)
adManager.tracking.requestAuthorization()
adManager.initialize(config, ConsentMode.InitializeOnlyIfAlreadyAllowed)
```
 Requesting ads before ATT resolves permanently forfeits the IDFA for those requests. Android has no ATT so `adManager.tracking` is a no-op there and always reports `AdTrackingAuthorization.NotApplicable`. The same ordering can be expressed with a hook instead of three calls, which is useful when the app wants a single `gatherConsentAndInitialize` entry point: 
```kotlin
AdConfig(
    androidAppId = "ca-app-pub-…",
    iosAppId = "ca-app-pub-…",
    initializationHooks = listOf(
        object : AdInitializationHook {
            override suspend fun onPhase(phase: AdInitializationPhase, config: AdConfig) {
                if (phase == AdInitializationPhase.BeforeMobileAdsInitialize) {
                    adManager.tracking.requestAuthorization()
                }
            }
        }
    ),
)
```
 The three phases are `BeforeConsentRequest`, `BeforeMobileAdsInitialize` and `AfterMobileAdsInitialize`. The ATT slot is the middle one, because it must run after the UMP gate and before native GMA initialisation. Hooks run exactly once per real native-initialization attempt, so cancelling one `initialize()` caller can never skip or duplicate a hook. The [App Tracking Transparency](/privacy/app-tracking-transparency/) guide has the full sequence diagram and the per-phase semantics. ## Why do I need to link JavaScriptCore? [Section titled “Why do I need to link JavaScriptCore?”](#why-do-i-need-to-link-javascriptcore) If the Kotlin framework is static and no Swift file imports `GoogleMobileAds`, nothing triggers autolinking of JavaScriptCore, which GMA needs. Add `-framework JavaScriptCore` to the app target’s `OTHER_LDFLAGS`. The symptom when it is missing is `Undefined symbol: _OBJC_CLASS_$_JSContext`. This is the one linker flag every static-Kotlin-framework iOS project needs but no one writes down. The [troubleshooting guide](/reference/troubleshooting/) treats it as a first-class failure with its own row in the symptom table. The flag is needed because GMA force-loads JavaScriptCore through `GADOMIDJSContextPool`, but a static Kotlin framework does not autolink transitive Objective-C dependencies the way a dynamic one does. Once any Swift file imports `GoogleMobileAds`, autolinking takes over and the flag becomes redundant — but the project still ships the flag because removing it would break the case where the Swift import is later removed. ## How do I verify the iOS setup? [Section titled “How do I verify the iOS setup?”](#how-do-i-verify-the-ios-setup) 
```bash
./gradlew :admob-cmp-core:doctorIos
```
 `doctorIos` is diagnostic only and never fails the build. It reports: * Whether the GoogleMobileAds and UserMessagingPlatform XCFramework download caches are present. * Whether the Xcode project references each SPM product. * Whether `Info.plist` declares `GADApplicationIdentifier`, and whether that value is still Google’s sample id. * Whether `SKAdNetworkItems` is present. The Xcode project directory can be overridden with `-PadmobCmp.xcodeproj=<dir>` if the standard search does not find it. For a KMP project with the Xcode project in `iosApp/`, the default behaviour finds it without flags. After `doctorIos` passes, run a real iOS build (`./gradlew :shared:iosSimulatorArm64Test` if Kotlin/Native tests are configured) to confirm the link is real and the Swift packages resolve. The doctor checks the configuration; only the test task proves the configuration is in the right state. ## What about Kotlin/Native test executables? [Section titled “What about Kotlin/Native test executables?”](#what-about-kotlinnative-test-executables) A Kotlin/Native test link has no Xcode and therefore cannot use SPM. The `dev.avinya.ads.admob-cmp` Gradle plugin is the supported fix, and it adds the linker options to test binaries only — leaving the shipped app framework alone for Xcode to bind via SPM. Adding another SPM package will not help, because SPM is not consulted during a Kotlin/Native test link. The full mechanic is on [Installation](/start/installation/) and the symptom table is on [Troubleshooting](/reference/troubleshooting/). This is the most common place new contributors to a KMP AdMob project lose an afternoon: the app builds and runs, then a CI job that runs Kotlin/Native tests fails with `_OBJC_CLASS_$_GADMobileAds` undefined even though the Xcode project compiles cleanly. The reason is that the two builds share the same Kotlin source but resolve GMA through completely different mechanisms, and the test link has no SPM-equivalent fallback. The plugin closes that gap for one specific build target — the test executable — and does so on macOS only, which is where the iOS test runner lives anyway. ## Where to next? [Section titled “Where to next?”](#where-to-next) [App Tracking Transparency](/privacy/app-tracking-transparency/)The consent to ATT to initialize sequence. [UMP consent](/privacy/consent/)Consent modes and canRequestAds. [Architecture](/reference/architecture/)Why iOS ships bindings only. [Troubleshooting](/reference/troubleshooting/)Undefined GAD and JSContext symbols.

---

# Using with AI agents

> Point an AI coding agent at AdMob Kotlin Multiplatform integration using AGENTS.md and llms.txt, so it writes code that compiles against the frozen API.

## Why does this page exist? [Section titled “Why does this page exist?”](#why-does-this-page-exist) A large share of SDK integration now happens through a coding assistant, and an assistant that guesses at an API produces code that does not compile against a frozen ABI. So the repository ships a file written **for** that reader. The cost of getting this wrong is asymmetric. A developer who reads the docs once and writes code by hand can correct themselves at the keyboard; an agent that runs end-to-end without supervision can publish code that compiles only by accident, then the agent’s next iteration drifts further from the real surface. The hard rules in `AGENTS.md` are the boundary that keeps an agent’s output in the same shape as a developer’s. ## What is AGENTS.md? [Section titled “What is AGENTS.md?”](#what-is-agentsmd) `AGENTS.md` is the agent-facing condensed guide. It contains the entry points (`rememberAdManager()` for Compose, `AdMob.manager(context)` for Android, `LocalAdPlacements` for shared placement lists), the canonical initialization snippet, a format-to-API table mapping each `AdFormat` to its controller, composable and test ad ids, the full-screen load/show pattern, the banner and native sections including geometry and pool accounting, the app-open coordinator, the consent and privacy-options rule, seven hard rules, the `testMode` versus `strictTestMode` distinction, executable iOS setup steps, and a symptom-to-fix troubleshooting table. The file lives at [`AGENTS.md`](https://github.com/Meet-Miyani/admob-compose-multiplatform/blob/master/admob-cmp/AGENTS.md). A note on what `AGENTS.md` is not. It is not a substitute for the full docs; it is a compressed, agent-targeted version that prioritises the things an agent gets wrong. The full [architecture reference](/reference/architecture/) has the design rationale; the [troubleshooting guide](/reference/troubleshooting/) has the symptom table; the per-format pages have the API patterns. An agent that has only `AGENTS.md` can write correct surface code but not correct diagnostic code — the full site is the source of truth, and `AGENTS.md` is the index into it. ## How do I point my agent at it? [Section titled “How do I point my agent at it?”](#how-do-i-point-my-agent-at-it) The durable form is a project instruction file — a `CLAUDE.md`, an `AGENTS.md`, or the equivalent — containing this instruction so it applies to every session rather than one prompt: 
```plaintext
Read https://github.com/Meet-Miyani/admob-compose-multiplatform/blob/master/admob-cmp/AGENTS.md
before writing any AdMob CMP code. Follow its hard rules exactly.
```
 For agents working inside a repository that depends on the library, the instruction lives in the project’s own instruction file. For one-off integrations, paste the URL into the prompt. ## What is llms.txt, and what does this site publish? [Section titled “What is llms.txt, and what does this site publish?”](#what-is-llmstxt-and-what-does-this-site-publish) `llms.txt` is a plain-text bundle of a site’s documentation, published at predictable paths so a language model can ingest the whole thing without crawling and parsing HTML. This site publishes three: | File | Purpose | | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | | [`/llms.txt`](/llms.txt) | Index. The entry point and table of contents for an agent that wants to read selectively. | | [`/llms-full.txt`](/llms-full.txt) | Full bundle. Every page, in order, for an agent that wants a complete offline context. | | [`/llms-small.txt`](/llms-small.txt) | Trimmed bundle, with the project and changelog pages excluded. For a context window that is tight but still needs every guide page. | The crawler policy: the documentation host allows AI crawlers deliberately. The [troubleshooting guide](/reference/troubleshooting/) is the single most useful page to paste into an agent’s context when a build is failing. Note that every diagram component ships with a prose equivalent that is included in the `llms.txt` bundle, so an agent reading the text bundle receives the content of every diagram even though it cannot see the SVG. The diagram is for the human reader; the prose equivalent is for the model. A practical note on which bundle to point an agent at. For a fresh integration, `/llms.txt` is enough — it gives the agent the index, the entry points, and the format table, and the agent can fetch specific pages by URL. For a focused troubleshooting session, paste the [troubleshooting page](/reference/troubleshooting/) directly into the context — the same content the bundle has, but with the surrounding context trimmed. For a session that needs every detail, `/llms-full.txt` is the right input; expect several hundred thousand tokens of context. ## Which rules do agents get wrong most often? [Section titled “Which rules do agents get wrong most often?”](#which-rules-do-agents-get-wrong-most-often) This is the section that makes the page genuinely useful rather than meta. A short list, each item one line, each drawn from the hard rules: * Constructing an `AdManager` implementation instead of using `rememberAdManager()` or `AdMob.manager(context)`. * Generating per-item placement ids such as `"feed_item_$index"`. Controllers are cached per id and never auto-evicted; reuse one placement id and let the native pool serve per-item ads. * Calling `show()` from `GlobalScope`. It suspends for the ad’s full on-screen lifetime and belongs in a UI-scoped coroutine. * Writing `TestAdIds.Android.BANNER`. The constants are flat: `TestAdIds.ANDROID_BANNER`. * Writing the `adLayout` DSL as property assignments. The nodes are functions with named arguments: `headline(maxLines = 2)`. * Assuming `testMode = true` serves test ads. It configures UMP consent debugging only. * Gating a privacy-settings button on `ConsentStatus.Obtained` instead of `PrivacyOptionsRequirementStatus.Required`. * Calling `pool.peek(...)`. It is not public API. * Relying on native video events on Android. Only iOS emits them. The full set of hard rules is in `AGENTS.md`; the troubleshooting table covers the common runtime errors. ## Where to next? [Section titled “Where to next?”](#where-to-next) [Troubleshooting](/reference/troubleshooting/)The best page to paste into an agent's context. [Contributing](/project/contributing/)The frozen ABI an agent must respect. [Quickstart](/start/quickstart/)The canonical integration shape.

---

# Roadmap

> What is next for AdMob CMP — the Kotlin Multiplatform SwiftPM import migration, the four gates it waits on, one unresolved question, and no promised dates.

## What is on the roadmap, and what is not promised? [Section titled “What is on the roadmap, and what is not promised?”](#what-is-on-the-roadmap-and-what-is-not-promised) This page describes intent, not commitments. **No item here has a date**, and none will get one until its blockers are cleared. The library is production-ready today, and everything below is about removing setup friction, not about missing functionality. | | | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Shipped** | Six ad formats, UMP consent in the init flow, mediation support, paid events, and the `dev.avinya.ads.admob-cmp` Gradle plugin for Kotlin/Native iOS test linking | | **Planned, gated** | SwiftPM import migration — removes both the Gradle plugin and the manual Xcode package step | | **Not planned** | Direct support for ad networks other than AdMob (mediation covers this), and renaming the published Maven coordinate | ## What is the SwiftPM import migration? [Section titled “What is the SwiftPM import migration?”](#what-is-the-swiftpm-import-migration) The Kotlin Gradle plugin has gained first-class Swift Package Manager dependencies via `swiftPMDependencies {}`. A Kotlin Multiplatform module declares the Swift package, and the Kotlin Gradle plugin resolves it and generates the cinterop bindings. The official documentation states the property that would make the current Gradle plugin unnecessary: > “For transitive dependencies (projects that depend on those that use SwiftPM import), the Kotlin Gradle plugin automatically provides the necessary machine code from SwiftPM dependencies. For example, you don’t need to do any additional configuration when running Kotlin/Native tests or linking a framework.” What shipping it would mean for a consumer, concretely: no `dev.avinya.ads.admob-cmp` plugin, no manually-added Swift packages in Xcode, and one added one-time `integrateLinkagePackage` step. It would raise the Kotlin floor for every consumer and would therefore ship as **2.0.0**, with the 1.x line continuing to receive fixes for as long as the ecosystem lags. A note on the “fixes for as long as the ecosystem lags” commitment. The 1.x line is not abandoned when 2.0.0 ships; it is maintained in parallel until the migration is provably complete for every consumer. The cost of a parallel line is small relative to the cost of a forced migration, and the library has stated this as policy in the [contributing guide](/project/contributing/) so the maintenance window is committed, not implied. ## Which four gates does it wait on? [Section titled “Which four gates does it wait on?”](#which-four-gates-does-it-wait-on) The gates, with the reason for each, exactly as the Track 3 plan defines them. None of them can be unblocked by work in this repository, which is the honest reason there is no date. ### Gate 1 — Kotlin 2.4.20 or later is a stable release [Section titled “Gate 1 — Kotlin 2.4.20 or later is a stable release”](#gate-1--kotlin-2420-or-later-is-a-stable-release) Not Beta, not RC. A published library must not be compiled by a pre-release compiler, because consumers cannot reliably resolve klibs produced by one. ### Gate 2 — SwiftPM import is no longer Alpha [Section titled “Gate 2 — SwiftPM import is no longer Alpha”](#gate-2--swiftpm-import-is-no-longer-alpha) A published SDK must not depend on an Alpha build-tool feature. The DSL shape itself is still subject to change while it carries that label. ### Gate 3 — KSP has a release for the target Kotlin version [Section titled “Gate 3 — KSP has a release for the target Kotlin version”](#gate-3--ksp-has-a-release-for-the-target-kotlin-version) Consumers using Room or Koin annotation processing cannot move to a Kotlin version KSP does not support, so shipping ahead of KSP would strand them. ### Gate 4 — Compose Multiplatform has a stable release for that Kotlin version [Section titled “Gate 4 — Compose Multiplatform has a stable release for that Kotlin version”](#gate-4--compose-multiplatform-has-a-stable-release-for-that-kotlin-version) The composable surface is part of the published artifact, so Compose Multiplatform must support the same Kotlin version. ## What is the one question nobody has answered yet? [Section titled “What is the one question nobody has answered yet?”](#what-is-the-one-question-nobody-has-answered-yet) Caution The blocking unknown: **does a Maven-published library that uses SwiftPM import actually carry its linkage to consumers?** What the documentation promises is scoped to *projects* — module-to- module dependencies inside one Gradle build. It says nothing about a klib resolved from Maven Central by a stranger. The direction of travel honestly: [KT-84420](https://youtrack.jetbrains.com/issue/KT-84420) concluded that Kotlin should start emitting a `Package.swift` structure describing the direct and transitive SwiftPM dependencies needed for linkage — that is, linkage requirements travel as **metadata the consumer resolves**, not as embedded binaries. Whether the equivalent reaches a Maven consumer’s `linkDebugTestIosSimulatorArm64` is exactly what has to be proven. The four steps the experiment will use: build a trivial Kotlin Multiplatform library declaring a `swiftPMDependencies` package and exposing one function touching its API; publish it to Maven Local; in a *separate* Gradle build with no SwiftPM declaration of its own, depend on it from `commonMain`, add a trivial test, and run `iosSimulatorArm64Test`; if it links, the migration is viable, and if it fails with undefined symbols, **the migration is dead for a published SDK**, because the consumer would then have to declare the SwiftPM dependency themselves — no better than today’s Gradle plugin and worse than the status quo, since it would also drag every consumer onto a new Kotlin minor. The secondary technical prerequisite settled by the same experiment: GoogleMobileAds’ `Package.swift` is a `.binaryTarget`, so `swiftPMDependencies` must handle binary-target packages. The official documentation’s own example is a binary distribution, which is encouraging evidence but not proof for this package specifically. A note on the experiment’s scope. It is intentionally a single trivial library, not a port of `admob-cmp` itself. The point of the experiment is to validate the metadata-passes-through-the- klink hypothesis, which is the only behaviour that matters for the migration’s viability. A negative result is conclusive; a positive result is suggestive but not yet a commitment to ship. ## Why not do what other SDKs do and embed the binary? [Section titled “Why not do what other SDKs do and embed the binary?”](#why-not-do-what-other-sdks-do-and-embed-the-binary) A factual contrast, no criticism of anyone. RevenueCat’s `purchases-kmp` 3.0.0 reaches the same outcome by a different route: a home-grown `swiftPackage` DSL in their own build logic that compiles `purchases-ios` **from source**, pinned as a git submodule, and statically links the result into the published artifact. That works because `purchases-ios` is open source. Google Mobile Ads is a closed-source prebuilt binary: there is no source to compile, and the XCFramework ships only third-party licences with no grant to redistribute GMA itself. Embedding Google’s binary in a `dev.avinya.ads` artifact would also reintroduce the duplicate Objective-C class problem that breaks mediation adapters — the exact thing the bindings-only design avoids. Same destination, different vehicle. The [architecture reference](/reference/architecture/) has the full rationale. ## What happens if the gates never clear? [Section titled “What happens if the gates never clear?”](#what-happens-if-the-gates-never-clear) Plainly, because it reassures rather than worries: the Gradle plugin is a perfectly serviceable permanent answer. It is a small amount of code in one place, it is dogfooded by this repository’s own modules, and it is invisible to consumers beyond a single `plugins {}` line. The migration will not happen on principle; it will happen when the official path is genuinely stable and the ecosystem has caught up. Until then, the plugin is the answer, and the [installation guide](/start/installation/) walks through it as the supported path. ## Where to next? [Section titled “Where to next?”](#where-to-next) [Architecture](/reference/architecture/)Why iOS ships bindings, not binaries. [Compatibility](/reference/compatibility/)Today's Kotlin floor, and the cinterop caveat. [Contributing](/project/contributing/)How to help move a gate. [Changelog](/reference/changelog/)What has already shipped.