Android SDK integration

Integrate the ironSource Android SDK using Gradle or manual download and configure app lifecycle, permissions, and ad unit listeners.

Read time 15 minutes

Prerequisites
Prerequisites

  • We support Android Operating Systems Version 4.4 (API level 19) and up.
  • The minimum supported Kotlin version is 1.7.0.

Step 1. Add the ironSource SDK to Your Project
Step 1. Add the ironSource SDK to Your Project

IronSource SDK supports both Gradle dependencies and manual download mechanisms to integrate our SDK:

Gradle
Gradle

  1. Add the following to your app's build.gradle file inside repositories section:

    repositories {
	mavenCentral()
}

  2. Add the following to the dependencies section:

dependencies {
    implementation 'com.unity3d.ads-mediation:mediation-sdk:8.10.0' 
}

Gradle version 7+

If you're using Gradle version 7+, update your repository section on your settings.gradle file, instead of build.gradle. Note the repository section should be included as part of the dependencyResolutionManagement section:

repositories {
	mavenCentral()
}

Manual Download
Manual Download

  1. Download Ad Quality SDK
  2. Import the .AAR file as a library project.
  3. If using Android Studio, download the ironSource .AAR file and add as a dependency to your own module.
  4. Go to File > New > New Module > Import .AAR and navigate to the location where the ironSource .AAR file has been downloaded.
  5. Note: ironSource Manifest Activities are included in the AAR.
  6. Ensure that you add the following to your build.gradle file under the dependencies section:
implementation(name: 'mediation-sdk-8.10.0', ext:'aar')
  1. As of ironSource SDK 7.0.4+ you are required to add the Kotlin JARs to your project. You can read more about Kotlin support here.

Optional: Manual JAR Integration
Optional: Manual JAR Integration

If you are using mediation-sdk-xxx.jar and adquality-sdk-xxx.jar in your project, you can still use the same configuration.  

  1. Rename the new mediation-sdk-xxx.aar to mediation-sdk-xxx.zip. 
  2. Rename the new adquality-sdk-xxx.jar to adquality-sdk-xxx.zip. 
  3. Extract the classes.jar
  4. Rename it to mediation-sdk-xxx.jar and adquality-sdk-xxx.jar. 
  5. Update AndroidManifest.xml

Update AndroidManifest.xml for Manual JAR Integration 

To update your AndroidManifest.xml, complete the following steps:

1.Manifest Permissions Add the following permissions to your AndroidManifest.xml file inside the manifest tag but outside the <application> tag**:**

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

  1. Manifest Activities and Provider Add this section inside the <application> tag in your AndroidManifest:

            <activity
            android:name="com.ironsource.sdk.controller.ControllerActivity"
            android:configChanges="orientation|screenSize"
            android:hardwareAccelerated="true"
            android:theme="@android:style/Theme.NoTitleBar" />
        <activity
            android:name="com.ironsource.sdk.controller.InterstitialActivity"
            android:configChanges="orientation|screenSize"
            android:hardwareAccelerated="true"
            android:theme="@android:style/Theme.Translucent.NoTitleBar" />
        <activity
            android:name="com.ironsource.sdk.controller.OpenUrlActivity"
            android:configChanges="orientation|screenSize"
            android:hardwareAccelerated="true"
            android:theme="@android:style/Theme.Translucent.NoTitleBar" />
        <activity
            android:name="com.ironsource.mediationsdk.testSuite.TestSuiteActivity"
            android:configChanges="orientation|screenSize"
            android:hardwareAccelerated="true"
            android:theme="@android:style/Theme.NoTitleBar" />
        <provider
            android:name="com.ironsource.lifecycle.IronsourceLifecycleProvider"
            android:authorities="${applicationId}.IronsourceLifecycleProvider" />

Demo Application
Demo Application

The Integration Demo application demonstrates how to integrate the LevelPlay Mediation in your app. [sdk_btn platform="android" type="demo"]

Step 2. Google identifier permissions
Step 2. Google identifier permissions

  1. Add the Play Services dependencies into the dependencies block, to allow GAID and APP Set ID information to be retrieved.

    dependencies { 
    implementation fileTree(dir: 'libs', include: ['*.jar']) 
    implementation 'com.google.android.gms:play-services-appset:16.0.0' 
    implementation 'com.google.android.gms:play-services-ads-identifier:18.1.0' 
    implementation 'com.google.android.gms:play-services-basement:18.1.0' 
}

    Learn more about Google’s app set ID here.

  2. Apps updating their target API level to 33 (Android 13) will need to declare a Google Play services normal permission in the manifest file as follows:

    <uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

    Read more about Google Advertising ID changes here.

Step 3. Override Your Activity Lifecycle Methods
Step 3. Override Your Activity Lifecycle Methods

Application Lifecycle Override the onPause(), onResume() methods in each of your activities to call the corresponding ironSource methods as follows:

protected void onResume() {
        super.onResume();
        IronSource.onResume(this);
    }
protected void onPause() {
        super.onPause();
        IronSource.onPause(this);
    }

Step 4. Set the Listeners
Step 4. Set the Listeners

  • For Rewarded Video

Rewarded Video ad unit uses the Legacy ironSource SDK. To receive events which inform you of your ad unit activity, register to the listener of the Rewarded Video ad unit you set up on the LevelPlay platform.

Make sure you set the rewarded video listener before initializing the SDK, to avoid any loss of information.

IronSource.setLevelPlayRewardedVideoListener(mLevelPlayRewardedVideoListener);
  • For Interstitial and Banner

Interstitial and Banner ad units use the LevelPlay Multiple Ad Unit SDK. Check their respective integration guides for ad listener implementations.

Step 5. Initialize the SDK
Step 5. Initialize the SDK

To initialize the ironSource SDK, follow these steps:

  1. Implement callbacks for initialization success and failure.
  2. Define the list of ad formats that require support from legacy ironSource API. This should include REWARDED. 
  3. Call the LevelPlay init API using the appKey, ad formats, and user ID if relevant.
// Init the SDK when implementing the Multiple Ad Units Interstitial and Banner APIs, and Rewarded using legacy APIs 
List<LevelPlay.AdFormat> legacyAdFormats = Arrays.asList(LevelPlay.AdFormat.REWARDED);

LevelPlayInitRequest initRequest = new LevelPlayInitRequest.Builder(appKey)
                               .withLegacyAdFormats(legacyAdFormats)
                               .withUserId("UserID")
                               .build();

LevelPlayInitListener initListener = new LevelPlayInitListener() {
    @Override
    public void onInitFailed(@NonNull LevelPlayInitError error) {
        //Recommended to initialize again 
    }
    @Override
    public void onInitSuccess(LevelPlayConfiguration configuration) {
        //Create ad objects and load ads 
    }
};
LevelPlay.init(context, initRequest, initListener);

// Init the SDK when implementing the Multiple Ad Units Interstitial and Banner APIs, and Rewarded using legacy APIs 
val legacyAdFormats = listOf(LevelPlay.AdFormat.INTERSTITIAL,LevelPlay.AdFormat.REWARDED)
val initRequest = LevelPlayInitRequest.Builder("AppKey")
                               .withLegacyAdFormats(legacyAdFormats)
                                   .withUserId("UserId")
                               .build()
LevelPlay.init(context, initRequest, object: LevelPlayInitListener {
   override fun onInitFailed(error: LevelPlayInitError) {
       //Recommended to initialize again
   }
   override fun onInitSuccess(configuration: LevelPlayConfiguration) {
       //Create ad objects and load ads
   }
})

LevelPlay Init Listeners
LevelPlay Init Listeners

OnInitSuccess – triggered when the initialization is completed successfully. After you receive this indication, you can create and load the ad.

OnInitFailed – the configuration was not retrieved successfully and ads cannot be loaded. It is recommended to try and initialize the ironSource SDK later (when internet connection is available, or when the failure reason is resolved).

For ProGuard Users Only
For ProGuard Users Only

If you are using ProGuard with the ironSource SDK, you must add the following code to your ProGuard file (Android Studio: proguard-rules.pro or Eclipse: proguard-project.txt):

-keepclassmembers class * implements android.os.Parcelable {
    public static final android.os.Parcelable$Creator *;
}
#noinspection ShrinkerUnresolvedReference
#unity
-keep class com.google.android.gms.ads.** {public *;}
-keep class com.google.android.gms.appset.** { *; }
-keep class com.google.android.gms.tasks.** { *; }
#adapters
-keep class com.ironsource.adapters.** { *; }
#sdk
-dontwarn com.ironsource.**
-dontwarn com.ironsource.adapters.**
-keepclassmembers class com.ironsource.** { public *; }
-keep public class com.ironsource.**
-keep class com.ironsource.adapters.** { *;
}
#omid
-dontwarn com.iab.omid.**
-keep class com.iab.omid.** {*;}
#javascript
-keepattributes JavascriptInterface
-keepclassmembers class * { @android.webkit.JavascriptInterface <methods>; }
#For AmazonAps integration
-keep class com.amazon.device.ads.DtbThreadService {
    static *;
}
-keep public interface com.amazon.device.ads** {*; }
#For AppLovin integration
-keepclassmembers class com.applovin.sdk.AppLovinSdk {
    static *;
}
-keep public interface com.applovin.sdk** {*; }
-keep public interface com.applovin.adview** {*; }
-keep public interface com.applovin.mediation** {*; }
-keep public interface com.applovin.communicator** {*; }
#For Bytedance integration
-keep public interface com.bytedance.sdk.openadsdk** {*; }
#For Facebook integration
-keepclassmembers class com.facebook.ads.internal.AdSdkVersion {
    static *;
}
-keepclassmembers class com.facebook.ads.internal.settings.AdSdkVersion {
    static *;
 }
-keepclassmembers class com.facebook.ads.BuildConfig {
    static *;
 }
-keep public interface com.facebook.ads** {*; }
#For Fairbid
-keep public interface com.fyber.fairbid.ads.interstitial** {*; }
-keep public interface com.fyber.fairbid.ads.rewarded** {*; }
-keep class com.fyber.offerwall.*
#For Fivead
-keep public interface com.five_corp.ad** {*; }
#For Fyber(Inneractive) integration
-keep public interface com.fyber.inneractive.sdk.external** {*; }
-keep public interface com.fyber.inneractive.sdk.activities** {*; }
-keep public interface com.fyber.inneractive.sdk.ui** {*; }
#For HyprMX integration
-keepclassmembers class com.hyprmx.android.sdk.utility.HyprMXProperties {
    static *;
}
-keepclassmembers class com.hyprmx.android.BuildConfig {
    static *;
}
-keep public interface com.hyprmx.android.sdk.activity** {*; }
-keep public interface com.hyprmx.android.sdk.graphics** {*; }
# For Inmobi integration
-keep class com.inmobi.*
-keep public interface com.inmobi.ads.listeners** {*; }
-keep public interface com.inmobi.ads.InMobiInterstitial** {*; }
-keep public interface com.inmobi.ads.InMobiBanner** {*; }
# For ironSource integration
-keep public interface com.ironsource.mediationsdk.sdk** {*; }
-keep public interface com.ironsource.mediationsdk.impressionData.ImpressionDataListener {*; }
#For Maio integration
-keep public interface jp.maio.sdk.android.MaioAdsListenerInterface {*; }
# For Mintergral integration
-keep public interface com.mbridge.msdk.out** {*; }
-keep public interface com.mbridge.msdk.videocommon.listener** {*; }
-keep public interface com.mbridge.msdk.interstitialvideo.out** {*; }
-keep public interface com.mintegral.msdk.out** {*; }
-keep public interface com.mintegral.msdk.videocommon.listener** {*; }
-keep public interface com.mintegral.msdk.interstitialvideo.out** {*; }
#For MyTarget integration
-keep class com.my.target.** {*;}
#For Ogury integration
-keep public interface io.presage.interstitial** {*; }
-keep public interface io.presage.interstitial.PresageInterstitialCallback {*; }
#For Pubnative integration
-keep public interface net.pubnative.lite.sdk.interstitial.HyBidInterstitialAd** {*; }
-keep public interface net.pubnative.lite.sdk.rewarded.HyBidRewardedAd** {*; }
-keep public interface net.pubnative.lite.sdk.views.HyBidAdView** {*; }
#For Smaato integration
-keep public interface com.smaato.sdk.interstitial** {*; }
-keep public interface com.smaato.sdk.video.vast** {*; }
-keep public interface com.smaato.sdk.banner.widget** {*; }
-keep public interface com.smaato.sdk.core.util** {*; }
# For Tapjoy integration
-keep public interface com.tapjoy.** {*; }
# For Tencent integration
-keep public interface com.qq.e.ads.interstitial2** {*; }
-keep public interface com.qq.e.ads.interstitial3** {*; }
-keep public interface com.qq.e.ads.rewardvideo** {*; }
-keep public interface com.qq.e.ads.rewardvideo2** {*; }
-keep public interface com.qq.e.ads.banner2** {*; }
-keep public interface com.qq.e.comm.adevent** {*; }
#For Verizon integration
-keepclassmembers class com.verizon.ads.edition.BuildConfig {
    static *;
}
-keep public interface com.verizon.ads.interstitialplacement** {*; }
-keep public interface com.verizon.ads.inlineplacement** {*; }
-keep public interface com.verizon.ads.vastcontroller** {*; }
-keep public interface com.verizon.ads.webcontroller** {*; }
#For Vungle integration
-keep public interface com.vungle.warren.PlayAdCallback {*; }
-keep public interface com.vungle.warren.ui.contract** {*; }
-keep public interface com.vungle.warren.ui.view** {*; }
#For AndroidX
-keep class androidx.localbroadcastmanager.content.LocalBroadcastManager { *;}
-keep class androidx.recyclerview.widget.RecyclerView { *;}
-keep class androidx.recyclerview.widget.RecyclerView$OnScrollListener { *;}
#For Android
-keep class * extends android.app.Activity

Step 6. Verify Your Integration
Step 6. Verify Your Integration

The ironSource SDK provides an easy way to verify that your integration was completed successfully with the LevelPlay integration test suite. Test your app’s integration, verify platform setup, and review ads related to your configured networks.

To enable the test suite in your app, call the setMetaData API before setting the init:

IronSource.setMetaData("is_test_suite", "enable");

After mediation init is completed successfully, launch the test suite by calling the following method (Application Context is required):

IronSource.launchTestSuite(context);

For more details and an implementation example of the LevelPlay integration test suite navigate to this article.

Next steps
Next steps

  1. Follow our integration guides to implement ad formats
  2. Integrate our Rewarded Video, Interstitial or Banner Ads in your app and follow our Mediation articles.
  3. Verify your integration with our Integration Test Suite.