A Kotlin Multiplatform ads library for Android and iOS, with Compose Multiplatform ad slots and a Google AdMob provider.

You declare placements and the policies they follow. The library decides whether each placement may show, tells you why when it may not, and takes care of frequency caps, warm-up, consent gating and persistence.

• Placements and policies as data. Frequency caps, warm-up, cooldowns and premium suppression are configuration, evaluated by a pure policy engine.
• Named suppression reasons. Every missing ad has a reason, such as RequiredSignalFalse(ads.consent_obtained) or DailyCapReached(12).
• Compose Multiplatform slots. AdBannerSlot reserves its height before the ad loads and the banner is built at exactly that size, adaptive, 320x50 or a fixed height, so the layout does not jump, including under mediation. AdNativeSlot renders through the SDK's own native ad view.
• Every AdMob format. Banner, native, interstitial, rewarded, rewarded interstitial and app open.
• Consent built in. Google's User Messaging Platform on Android, and the same flow through a Swift adapter on iOS. No ad is requested until consent resolves.
• Safe test ads. Debug builds resolve every placement to Google's demo units, and live ids are validated at startup.
• No native interop on iOS. The library links no ad SDK. Your app adds Google Mobile Ads with Swift Package Manager and implements one Swift protocol.
• Testable. ads-testing provides a fake provider, a controllable clock and an event recorder.

kmp-ads is published to Maven Central. The AdMob SDK comes from Google's Maven repository, so keep both repositories:

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

# gradle/libs.versions.toml
[versions]
kmpads = "1.0.0"

[libraries]
kmpads-core = { module = "io.github.shivathapaa.kmpads:ads-core", version.ref = "kmpads" }
kmpads-compose = { module = "io.github.shivathapaa.kmpads:ads-compose", version.ref = "kmpads" }
kmpads-admob-android = { module = "io.github.shivathapaa.kmpads:ads-admob-android", version.ref = "kmpads" }
kmpads-bridge-ios = { module = "io.github.shivathapaa.kmpads:ads-bridge-ios", version.ref = "kmpads" }
kmpads-testing = { module = "io.github.shivathapaa.kmpads:ads-testing", version.ref = "kmpads" }

// the shared module's build.gradle.kts
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(libs.kmpads.core)
            implementation(libs.kmpads.compose)
        }
        androidMain.dependencies {
            implementation(libs.kmpads.admob.android)
        }
        iosMain.dependencies {
            api(libs.kmpads.bridge.ios)
        }
        commonTest.dependencies {
            implementation(libs.kmpads.testing)
        }
    }
}

ads-bridge-ios is an api dependency because your iOS framework exports it. See iOS setup.

Declare your placements:

object Placements {
    val HomeBanner = AdPlacement(
        id = AdPlacementId("home_banner"),
        format = AdFormat.Banner,
        policy = AdPolicy.InlineDefault,
    )
    val LevelComplete = AdPlacement(
        id = AdPlacementId("level_complete"),
        format = AdFormat.Interstitial,
        policy = AdPolicy.FullScreenDefault,
    )
    val all = listOf(HomeBanner, LevelComplete)
}

Create the ads system. On Android:

class App : Application() {
    lateinit var ads: AdsSystem
    lateinit var consent: AdConsentController

    override fun onCreate() {
        super.onCreate()
        val adMob = AdMobAndroid.install(
            application = this,
            audience = AdAudienceConfig.GeneralAudience,
        )
        consent = adMob.consentController
        ads = AdsSystem.create(
            AdsConfig(
                placements = Placements.all,
                units = AdUnitRegistry.testOnly(),
                provider = adMob.provider,
                platform = AdPlatform.Android,
                audience = AdAudienceConfig.GeneralAudience,
                scope = CoroutineScope(SupervisorJob() + Dispatchers.Main.immediate),
                signals = mapOf(
                    AdSignalKey.ConsentObtained to consent.state.map { it.canRequestAds },
                    AdSignalKey.NetworkAvailable to flowOf(true),
                    AdSignalKey.UserIsPremium to flowOf(false),
                ),
                hostDeclaresDebugBuild = BuildConfig.DEBUG,
            )
        ).orNoOp()
    }
}

Gather consent once an Activity is resumed:

override fun onResume() {
    super.onResume()
    lifecycleScope.launch { (application as App).consent.gather() }
}

Provide the system at the root of your UI and place ads:

CompositionLocalProvider(LocalAds provides ads) {
    Scaffold(
        bottomBar = { AdBannerSlot(placement = Placements.HomeBanner.id) },
    ) { padding ->
        // Screen content
    }
}

Show a full-screen ad at a natural break:

scope.launch {
    when (val outcome = ads.show(Placements.LevelComplete.id)) {
        is AdShowOutcome.Completed -> outcome.reward?.let { grantReward(it) }
        is AdShowOutcome.Suppressed -> log("Not shown: ${outcome.reason}")
        AdShowOutcome.NotReady -> log("Nothing loaded yet")
        is AdShowOutcome.Failed -> log("Failed: ${outcome.error}")
    }
}

On iOS the ads system is built the same way, with iosAdProvider(host) and iosConsentController(host). The host is a small Swift adapter over Google Mobile Ads that you copy from the sample. The integration guide covers both platforms step by step.

The sample app shows every format, the live decision for each placement and the event stream. It uses Google's demo ad units only.

./gradlew :sample:androidApp:installDebug   # Android
open sample/iosApp/iosApp.xcodeproj         # iOS, then run in Xcode

The iOS project resolves Google Mobile Ads through Swift Package Manager and builds the Kotlin framework itself.

• Integration guide: setup on Android and iOS, placements, signals, ad unit ids and testing.
• iOS setup: the Swift adapter and the framework export.
• Ad policy: placement rules, consent and invalid-traffic safety.
• Changelog: what changed in each release, and what to do when upgrading.

Copyright 2026 Shiva Thapa

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.