Skip to main content

Integration

This guide explains how to install the React Native bridge and configure both Android and iOS native projects.

Step 1: Install the Package​

npm install @empower-nokta/react-native-mobile-ads

The package supports autolinking — no manual native linking is needed.

This guide covers version 1.0.12, which uses native Android SDK 5.9.9.

Step 2: Android Configuration​

Add the Maven Repository​

Add the Empower Maven repository to your project-level android/build.gradle:

// android/build.gradle
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://maven.empower.net/release' }
    }
}

Or if your project uses settings.gradle (newer RN versions):

// android/settings.gradle
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://maven.empower.net/release' }
    }
}

Configure AndroidManifest​

Add the following <meta-data> tags inside the <application> block of android/app/src/main/AndroidManifest.xml:

<application>
    <!-- Existing configuration -->

    <meta-data
        android:name="com.google.android.gms.ads.AD_MANAGER_APP"
        android:value="true"/>

    <meta-data
        android:name="com.google.android.gms.ads.APPLICATION_ID"
        android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
</application>

Note: Replace the APPLICATION_ID value with your actual Google Ads Application ID. Contact Empower support if you need assistance obtaining this ID.

Kotlin Version Compatibility​

The Empower native SDK is compiled with Kotlin 2.2.0. If your project uses an older Kotlin compiler (1.9.x), you may see a version compatibility warning. Add this line to android/gradle.properties:

# Empower Mobile Ads SDK — Kotlin compatibility
kotlin.suppressKotlinVersionCompatibilityCheck=2.2.0

That's it — the SDK automatically injects the -Xskip-metadata-version-check compiler flag into all Kotlin compile tasks, so no additional Gradle configuration is needed.

⚠️ Important: Do not use resolutionStrategy.force to downgrade kotlin-stdlib to 1.9.x. The Empower SDK depends on Kotlin 2.x coroutine classes (such as SpillingKt) at runtime. Forcing a stdlib downgrade will cause a NoClassDefFoundError crash.

New Architecture (React Native 0.76+)​

If your app uses the New Architecture (Fabric / TurboModules), update MainApplication.kt to use OpenSourceMergedSoMapping for SoLoader initialization:

// android/app/src/main/java/.../MainApplication.kt
import com.facebook.react.soloader.OpenSourceMergedSoMapping
import com.facebook.soloader.SoLoader

// In onCreate():
SoLoader.init(this, OpenSourceMergedSoMapping)

React Native 0.76+ merges several native libraries into libreactnative.so. Without this mapping, SoLoader cannot find the merged libraries and the app will crash on startup with a libreact_featureflagsjni.so not-found error.

Note: This change is only required for New Architecture. Old Architecture apps should keep the default SoLoader.init(this, false).

Note: Apps created from a recent React Native template call loadReactNative(this) in MainApplication.kt, which already does this. Leave that call as it is.

Core Library Desugaring​

The Empower SDK uses Java 8+ APIs that are not available on older Android versions without desugaring. Enable core library desugaring in your android/app/build.gradle:

// android/app/build.gradle
android {
    compileOptions {
        coreLibraryDesugaringEnabled true
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
}

dependencies {
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.1.5'
}

Note: Desugaring is required whatever your minSdk. Without it the build stops with requires core library desugaring to be enabled.

DEX Code Optimization​

From February 2027 Google Play requires release builds to reach at least 25% in DEX code optimization. Apply the two steps below so your app meets this requirement.

Step 1: Add the optimization block to the release build type in android/app/build.gradle.

// android/app/build.gradle
android {
    buildTypes {
        release {
            // your existing settings
            optimization {
                keepRules {
                    ignoreFrom("com.applovin.mediation:vungle-adapter",
                               "com.applovin.mediation:inmobi-adapter",
                               "com.google.ads.mediation:inmobi")
                }
            }
        }
    }
}

Note: The ignoreFrom call needs Android Gradle Plugin 8.6 or newer.

Step 2: Add these rules to android/app/proguard-rules.pro.

-keep class com.vungle.ads.** { *; }
-keep class com.inmobi.** { *; }
-keep class com.squareup.picasso.** { *; }
-keep class androidx.browser.customtabs.CustomTabsService { *; }
-keep class androidx.recyclerview.widget.RecyclerView { *; }
-keep class * implements com.google.gson.TypeAdapterFactory
-keep class * implements com.google.gson.JsonSerializer
-keep class * implements com.google.gson.JsonDeserializer
-keepattributes Signature
-keepattributes *Annotation*
-dontwarn com.inmobi.**
-dontwarn com.squareup.okhttp.**
-dontwarn com.moat.**
-dontwarn sun.misc.**

Step 3: iOS Configuration​

Update Your Podfile (before installing)​

⚠️ Order matters. Add the Empower specs source and use_frameworks! to your Podfile first, then run pod install. If you install before adding the source, CocoaPods cannot resolve EmpowerMobileAds and the build fails with "Native module not found".

Add the Empower specs source to the top of your ios/Podfile:

source 'https://github.com/empowernet/specs.git'
source 'https://cdn.cocoapods.org/'

Ensure use_frameworks! is present in your target block:

target 'YourApp' do
  use_frameworks!
  # ...existing pods...
end

Install CocoaPods Dependencies​

Now install (use --repo-update so the specs repo is fetched):

cd ios && pod install --repo-update && cd ..

Updating to a New Version (iOS)​

After updating the npm package, update the native pods too. pod install alone keeps the native SDK version locked in Podfile.lock:

npm install @empower-nokta/react-native-mobile-ads@latest
cd ios && pod update EmpowerMobileAds empower-mobile-ads && cd ..

Update Info.plist​

Add your Google Ads Application ID to ios/YourApp/Info.plist:

<key>GADApplicationIdentifier</key>
<string>ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy</string>

Configure SKAdNetwork​

Required for production. Ad networks use SKAdNetwork to attribute installs on iOS without tracking the user; if a network's ID isn't listed, it can't attribute conversions, which lowers your fill and revenue. Add an SKAdNetworkItems array to your Info.plist:

<key>SKAdNetworkItems</key>
<array>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>cstr6suwn9.skadnetwork</string>
    </dict>
    <!-- …add the full list here -->
</array>

Ask Empower for the current SKAdNetwork ID list to add here.

Update Build Settings​

Add ${inherited} to Other Linker Flags in your Xcode project:

Target → Build Settings → Other Linker Flags

Step 4: Build and Run​

# Android
npx react-native run-android

# iOS
npx react-native run-ios

Mediation Adapters​

Android​

Configure Repositories​

Pick the path that matches your build policy. The settings plugin is the default and stays in sync with the SDK automatically. Use the manual setup only when third-party Gradle plugins are restricted in your project.

Standard setup (settings plugin)​

Add the Empower maven to pluginManagement.repositories, then apply the settings plugin. The plugin registers every Maven repo the SDK and its mediation adapters need (Empower, AppLovin, Pangle, IronSource, Ogury, Mintegral). Bumping the plugin version is enough when networks change in a future release. Use the plugin version that matches the native SDK of your package, 5.9.9 for 1.0.12.

android/settings.gradle.kts
pluginManagement {
  repositories {
      google()
      mavenCentral()
      gradlePluginPortal()
      maven { url = uri("https://maven.empower.net/release") }
  }
}

plugins {
  id("net.empower.mobile.ads.settings") version "5.9.9"
}

If your project already declares dependencyResolutionManagement (including with repositoriesMode = FAIL_ON_PROJECT_REPOS), the plugin appends to it without conflict.

Without the settings plugin​

Declare every Maven repository the SDK needs yourself. You will need to add new repositories manually when the SDK adds networks in future releases.

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

        // Empower Mobile Ads SDK
        maven {
            url = uri("https://maven.empower.net/release")
            content { includeGroup("net.empower.mobile.ads") }
        }
        // AppLovin SDK & mediation adapters
        maven {
            url = uri("https://artifacts.applovin.com/android")
            content { includeGroupByRegex("com\\.applovin.*") }
        }
        // Pangle / ByteDance
        maven {
            url = uri("https://artifact.bytedance.com/repository/pangle/")
            content { includeGroupByRegex("com\\.(bytedance|pangle).*") }
        }
        // IronSource / Fyber / DT Exchange
        maven {
            url = uri("https://android-sdk.is.com/")
            content { includeGroupByRegex("com\\.(ironsource|fyber).*") }
        }
        // Ogury
        maven {
            url = uri("https://maven.ogury.co")
            content { includeGroupByRegex("co\\.ogury.*") }
        }
        // Mintegral
        exclusiveContent {
            forRepository {
                maven { url = uri("https://dl-maven-android.mintegral.com/repository/mbridge_android_sdk_oversea") }
            }
            filter { includeGroupByRegex("com\\.mbridge.*") }
        }
    }
}

iOS​

Installing EmpowerMobileAds already pulls in Google Mobile Ads, the AppLovin SDK, Google IMA, and Amazon Publisher Services — don't add those yourself. Add the adapter pods for the networks Empower has enabled for your account to your ios/Podfile:

target 'YourApp' do
  use_frameworks!

  # AppLovin MAX adapters
  pod 'AppLovinMediationGoogleAdManagerAdapter'  # Google Ad Manager
  pod 'AppLovinMediationGoogleAdapter'           # Google / AdMob bidding
  pod 'AppLovinMediationByteDanceAdapter'        # Pangle
  pod 'AppLovinMediationFacebookAdapter'         # Meta Audience Network
  pod 'AppLovinMediationFyberAdapter'            # DT Exchange (Fyber)
  pod 'AppLovinMediationInMobiAdapter'           # InMobi
  pod 'AppLovinMediationMintegralAdapter'        # Mintegral
  pod 'AppLovinMediationOguryPresageAdapter'     # Ogury
  pod 'AppLovinMediationUnityAdsAdapter'         # Unity Ads
  pod 'AppLovinMediationVungleAdapter'           # Liftoff Monetize (Vungle)
  pod 'AppLovinMediationYandexAdapter'           # Yandex

  # Google Mobile Ads (GAM) mediation adapters
  pod 'GoogleMobileAdsMediationInMobi'           # InMobi
  pod 'GoogleMobileAdsMediationMintegral'        # Mintegral
  pod 'GoogleMobileAdsMediationPangle'           # Pangle
  pod 'GoogleMobileAdsMediationUnity'            # Unity Ads
end

Then run cd ios && pod install --repo-update.

Note: Contact your Empower account manager for the recommended adapter configuration based on your target markets and revenue goals.

Troubleshooting​

Native Module Not Found​

If you see @empower-nokta/react-native-mobile-ads: Native module not found:

Android:

  1. Run: cd android && ./gradlew clean && cd .. && npx react-native run-android
  2. Ensure maven { url 'https://maven.empower.net/release' } is in android/build.gradle

iOS:

  1. Run: cd ios && pod install && cd .. && npx react-native run-ios
  2. Ensure source 'https://github.com/empowernet/specs.git' is in your Podfile
  3. Ensure use_frameworks! is in your Podfile

Kotlin Version Mismatch​

If you see errors about Kotlin version incompatibility, add kotlin.suppressKotlinVersionCompatibilityCheck=2.2.0 to android/gradle.properties as described in the Android Configuration section above. Do not force-downgrade kotlin-stdlib — this causes runtime crashes.

App Crashes on Startup (New Architecture)​

If you see libreact_featureflagsjni.so not found or similar SO loading errors, make sure you're using SoLoader.init(this, OpenSourceMergedSoMapping) in MainApplication.kt. See the New Architecture section above.

Could Not Find mbridge_android_sdk​

If the Android build stops with Could not find com.mbridge.msdk.oversea:mbridge_android_sdk, update the package to 1.0.12 or newer. If your settings.gradle lists the repositories itself, add the Mintegral block shown in Without the settings plugin.

Release Build Crashes at Launch​

If a release build with minification crashes at launch with Failed to create an instance of androidx.work.impl.WorkDatabase, update the package to 1.0.12 or newer.

Build Asks for Core Library Desugaring​

If the build stops with requires core library desugaring to be enabled, enable it as shown in Core Library Desugaring.

Play Console Warns About DEX Code Optimization​

If Play Console shows that DEX code optimization is below the threshold, apply the changes in DEX Code Optimization.

Build Fails After Adding Mediation Adapters​

Run a clean build:

# Android
cd android && ./gradlew clean && cd ..

# iOS
cd ios && pod deintegrate && pod install --repo-update && cd ..