From fa05a06b6e508373a931cbcab3b21b6ff6d25d8d Mon Sep 17 00:00:00 2001 From: Floze <88098863+floze-the-genius@users.noreply.github.com> Date: Sun, 19 Jul 2026 13:37:39 +0400 Subject: [PATCH 1/2] fix(android): allow older Kotlin compilers with ads SDK 25.4 --- android/build.gradle | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/android/build.gradle b/android/build.gradle index 8a31e69b..28bd06f7 100644 --- a/android/build.gradle +++ b/android/build.gradle @@ -34,6 +34,11 @@ plugins { } apply plugin: 'kotlin-android' +tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach { + // Google Mobile Ads 25.3+ contains Kotlin 2.3 metadata, but this module only consumes its Java API. + kotlinOptions.freeCompilerArgs += ["-Xskip-metadata-version-check"] +} + def packageJson = PackageJson.getForProject(project) def googleMobileAdsVersion = packageJson['sdkVersions']['android']['googleMobileAds'] def googleUmpVersion = packageJson['sdkVersions']['android']['googleUmp'] @@ -143,4 +148,3 @@ ReactNative.shared.applyPackageVersion() ReactNative.shared.applyDefaultExcludes() ReactNative.module.applyAndroidVersions() ReactNative.module.applyReactNativeDependency("api") - From 12b606c6b29c6cea4d2b8ad1fcec236aea536688 Mon Sep 17 00:00:00 2001 From: Mike Hardy Date: Mon, 17 Aug 2026 01:04:21 -0500 Subject: [PATCH 2/2] test(android): verify kotlin 2.1 works, gate workaround for kotlin <2.3.0, docs - Pin example KOTLIN_VERSION to 2.1.0 so Ads 25.4 metadata path is exercised - Gate -Xskip-metadata-version-check to Kotlin compilers older than 2.3 - Document Android Kotlin 2.1 / Ads 25.3+ compatibility options in index docs --- .../android/gradle.properties | 3 +- android/build.gradle | 27 +++++++++++-- docs/index.mdx | 40 +++++++++++++++++++ 3 files changed, 66 insertions(+), 4 deletions(-) diff --git a/RNGoogleMobileAdsExample/android/gradle.properties b/RNGoogleMobileAdsExample/android/gradle.properties index 5309ac6f..b11febe0 100644 --- a/RNGoogleMobileAdsExample/android/gradle.properties +++ b/RNGoogleMobileAdsExample/android/gradle.properties @@ -50,4 +50,5 @@ newArchEnabled=true #ANDROID_NDK_VERSION=26.1.10909125 # Version of Kotlin to build against. -KOTLIN_VERSION=2.3.0 \ No newline at end of file +# Keep on 2.1.x so CI/example builds exercise Ads 25.4+ metadata compatibility. +KOTLIN_VERSION=2.1.0 \ No newline at end of file diff --git a/android/build.gradle b/android/build.gradle index 28bd06f7..231774e6 100644 --- a/android/build.gradle +++ b/android/build.gradle @@ -34,9 +34,30 @@ plugins { } apply plugin: 'kotlin-android' -tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach { - // Google Mobile Ads 25.3+ contains Kotlin 2.3 metadata, but this module only consumes its Java API. - kotlinOptions.freeCompilerArgs += ["-Xskip-metadata-version-check"] +// Ads 25.3+ ships Kotlin 2.3 metadata. Older compilers reject that unless we skip +// the metadata version check. Only needed while compiling this module with Kotlin < 2.3. +def kotlinVersionForCompile = { + if (project.rootProject.ext.has('kotlinVersion')) { + return project.rootProject.ext.kotlinVersion.toString() + } + if (project.hasProperty('KOTLIN_VERSION')) { + return project.property('KOTLIN_VERSION').toString() + } + return getExtOrDefault('kotlinVersion', '1.8.22').toString() +}() + +def kotlinNeedsAdsMetadataSkip = { + def parts = kotlinVersionForCompile.tokenize('.')*.toInteger() + def major = parts.size() > 0 ? parts[0] : 0 + def minor = parts.size() > 1 ? parts[1] : 0 + return major < 2 || (major == 2 && minor < 3) +}() + +if (kotlinNeedsAdsMetadataSkip) { + tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach { + // This module only consumes the Ads Java API; skip metadata version checks on Kotlin < 2.3. + kotlinOptions.freeCompilerArgs += ["-Xskip-metadata-version-check"] + } } def packageJson = PackageJson.getForProject(project) diff --git a/docs/index.mdx b/docs/index.mdx index a593a0aa..95381a52 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -77,6 +77,46 @@ To do so [follow the official `expo-build-properties` installation instructions] +### Android Kotlin compatibility (Google Mobile Ads 25.3+) + +Google Mobile Ads Android SDK 25.3+ includes Kotlin **2.3** metadata. +Apps still compiling with Kotlin **2.1.x** (common on some Expo / React Native setups) +can fail with: + +```text +Module was compiled with an incompatible version of Kotlin. +The binary version of its metadata is 2.3.0, expected version is 2.1.0. +``` + +For normal use of this library, you should **not** need to change anything: +`react-native-google-mobile-ads` only consumes the Ads **Java** API and, when +built with Kotlin < 2.3, configures its own Kotlin compile tasks with +`-Xskip-metadata-version-check`. + +You **do** need an app-side change if: + +- your app (or another module) depends on `play-services-ads` with `api` / compiles Ads APIs from Kotlin directly, or +- you prefer to fix forward by upgrading Kotlin instead of relying on the skip. + +**Option A — upgrade Kotlin (preferred long-term)** + +- Bare RN: set `kotlinVersion` / `KOTLIN_VERSION` to `2.3.0` (or newer) in your Android Gradle config. +- Expo: use [`expo-build-properties`](https://docs.expo.dev/versions/latest/sdk/build-properties/) and set `android.kotlinVersion` to `"2.3.0"`. + +**Option B — pin an older library release** + +If you cannot upgrade yet, pin an exact older package that still used Ads < 25.3, e.g. `"react-native-google-mobile-ads": "16.3.4"`. + +**Option C — apply the skip in your app** + +Only if *your* `:app` Kotlin compile hits the Ads metadata error: + +```groovy +tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach { + kotlinOptions.freeCompilerArgs += ["-Xskip-metadata-version-check"] +} +``` + ### Setting up Google AdMob Before you are able to display ads to your users, you must have a [Google AdMob account](https://apps.admob.com). Under the