MoPub
  1. publishers
  2. Android SDK
  3. Integrate the MoPub SDK for Android

Integrate the MoPub SDK for Android

NEW: Check out the Integration Suite for a faster way to integrate the MoPub SDK.

Use these instructions to integrate the MoPub SDK with your Android app. If you are upgrading to our version 5.0.0 or higher of our SDK, refer to the SDK Initialization and GDPR sections for additional steps.

High-Level Steps to Integrate

  1. Download the MoPub Android SDK
  2. Add the MoPub SDK to your project
  3. Update your Android Manifest (skip if using v5.10.0 or newer)
  4. Optionally use Proguard
  5. Configure ad units in your app

Step 1. Download the MoPub Android SDK

We recommend that you download the MoPub SDK via Maven Central, but it is also available as a zipped source code file, or as a cloned GitHub Repository.

The MoPub Android SDK has been moved to mavenCentral() because JCenter is officially deprecated and retired by Jfrog.

The MoPub SDK is available as an AAR via Maven Central.

To add the MoPub SDK dependency, open your project and update the app module’s build.gradle to include the following repositories and dependencies:

repositories {
    // ... other project repositories
    mavenCentral() // MoPub SDK is now available in Maven Central
    jcenter() // jcenter will be deprecated, use mavenCentral()
}

// ...

dependencies {
    // ... other project dependencies

    // This will get the latest available version of the MoPub SDK.
    // Alternatively, you may specify a specific version from the changelog to download.
    implementation('com.mopub:mopub-sdk:+@aar') {
        transitive = true
    }
}

  • Add the dependencies listed here if you integrate the MoPub Android SDK as a standalone AAR, and not via Bintray/JCenter.

  • We strongly recommend compiling your app against the ads dependencies from Google Play services in order to use the Android Advertising ID instead of the device ID, as required by Google. Those dependencies are com.google.android.gms:play-services-ads-identifier and com.google.android.gms:play-services-base.

  • To support Java 8, add the language feature support:

      android {
      compileOptions {
          sourceCompatibility JavaVersion.VERSION_1_8
          targetCompatibility JavaVersion.VERSION_1_8
      }
  }

SDK Modularization

With the modular SDK, you can choose to include specific formats to decrease overall SDK footprint in your app. To do so, include the line for any combination of components that you want in your build.gradle file as follows:

dependencies {
    // ... other project dependencies

    // For banners
    implementation('com.mopub:mopub-sdk-banner:+@aar') {
        transitive = true
    }

    // For fullscreen ads
    implementation('com.mopub:mopub-sdk-fullscreen:+@aar') {
        transitive = true
    }

    // For native static (images).
    implementation('com.mopub:mopub-sdk-native-static:+@aar') {
        transitive = true
    }

If you integrate an SDK version older than 5.13.0, add these dependencies:

repositories {
    // ... other project repositories
    mavenCentral() // includes the MoPub SDK
}
// ...

dependencies {
    // ... other project dependencies

    // For banners
    implementation('com.mopub:mopub-sdk-banner:+@aar') {
        transitive = true
    }

    // For interstitials
    implementation('com.mopub:mopub-sdk-interstitial:+@aar') {
        transitive = true
    }

    // For rewarded ads. This will automatically also include interstitials
    implementation('com.mopub:mopub-sdk-rewardedvideo:+@aar') {
        transitive = true
    }

    // For native static (images).
    implementation('com.mopub:mopub-sdk-native-static:+@aar') {
        transitive = true
    }
}

To continue integration using the mopub-sdk AAR, skip the next few sections and continue to the Step 3. Update your Android Manifest section.

Option 2. Zipped Source

The MoPub SDK is also distributed as zipped source code that you can include in your application.

MoPub Android SDK.zip

This includes everything you need to serve MoPub ads. No third-party ad networks are included.

Option 3. Cloned GitHub Repository

Alternatively, you can obtain the MoPub SDK source by cloning the Git repository:

git clone git://github.com/mopub/mopub-android-sdk.git

Step 2. Add the MoPub SDK to Your Project

You can use the non-jCenter Gradle integration, adding the MoPub SDK as either a source or a compiled .aar file; or use the Maven integration option.

Option 1. Gradle Integration

With the Gradle integration, you can add the MoPub SDK as a source or as a compiled .aar file.

Adding the MoPub SDK as a Source

To include the MoPub SDK as source in your project, copy the SDK source into your project as a module. To do this on OS X and Linux:

  1. Run this command:

     $MY_PROJECT_DIR $ mkdir mopub-sdk
 $MY_PROJECT_DIR $ cp -R $MOPUB_DIR/mopub-android-sdk/mopub-sdk mopub-sdk

  2. Next, open your project’s settings.gradle file and make sure the MoPub SDK is included as a module:

     include ':app', ':mopub-sdk'

  3. Open your project’s build.gradle file and add mavenCentral() as a repository and the MoPub SDK as a dependency:

     repositories {
     mavenCentral() // includes the MoPub SDK
 }

 // ...

 dependencies {
     implementation project(':mopub-sdk')
     // ...
 }

    This is required in order to resolve the MoPub SDK’s compile time dependency on com.mopub.volley:mopub-volley:2.1.0.

SDK Modularization

Modularization is also possible from the source code directly:

  1. Open your project’s settings.gradle file and add these modules in addition to your app.

       include ':app', ':mopub-sdk', ':mopub-sdk:mopub-sdk-base', ':mopub-sdk:mopub-sdk-banner',
        ':mopub-sdk:mopub-sdk-fullscreen', ':mopub-sdk:mopub-sdk-native-static'

    If you integrate an SDK version older than 5.13.0, include the follow modules in settings.gradle:

    include ':app', ':mopub-sdk', ':mopub-sdk:mopub-sdk-base', ':mopub-sdk:mopub-sdk-banner',
        ':mopub-sdk:mopub-sdk-interstitial', ':mopub-sdk:mopub-sdk-rewardedvideo',
        ':mopub-sdk:mopub-sdk-native-static'

  2. Open your project’s build.gradle file and add mavenCentral() as a repository and whichever ad formats you want as a dependency:

          repositories {
         mavenCentral() // includes the MoPub SDK
}
// ...

dependencies {
    // ... other project dependencies

    // For banners
    implementation project(':mopub-sdk:mopub-sdk-banner')

    // For fullscreen ads
    implementation project(':mopub-sdk:mopub-sdk-fullscreen')

    // For native static (images).
    implementation project(':mopub-sdk:mopub-sdk-native-static')
}

    If you integrate an SDK version older than 5.13.0, add these dependencies:

    repositories {
    mavenCentral() // includes the MoPub SDK
}
// ...

dependencies {
    // ... other project dependencies

    // For banners
    implementation project(':mopub-sdk:mopub-sdk-banner')

    // For interstitials
    implementation project(':mopub-sdk:mopub-sdk-interstitial')

    // For rewarded ads. This will automatically also include interstitials
    implementation project(':mopub-sdk:mopub-sdk-rewardedvideo')

    // For native static (images).
    implementation project(':mopub-sdk:mopub-sdk-native-static')
}

Adding the MoPub SDK as a Compiled .aar

To add the MoPub SDK as an .aar in your project:

  1. Navigate to the MoPub SDK in your terminal and run the following command:

    ./gradlew mopub-sdk:build

    This will build an AAR that bundles the mopub-sdk. You can also download the MoPub SDK .aar here.

  2. Copy the .aar to your library directory:

    cp mopub-sdk/build/outputs/aar/mopub-sdk.aar $MY_LIB_DIR

    where $MY_LIB_DIR is your default library directory.

    Note: If you are adding third-party network SDKs and adapters, and you receive a dex error, you may need to enable multidexing in your build.gradle file. Refer to the Android documentation.

    defaultConfig {
 multiDexEnabled true
}

  3. Open your project’s build.gradle file and add the following lines:

    repositories {
    mavenCentral() // includes the MoPub SDK
    flatDir {
        dirs '$MY_LIB_DIR'
    }
}

// ...

dependencies {
    implementation(name:'mopub-sdk', ext:'aar')
    implementation 'com.mopub.volley:mopub-volley:2.1.0'
}

    Note: If you are adding third-party network SDKs and adapters, and you receive a dex error, you may need to enable multidexing in your build.gradle file. Refer to the Android documentation.

     defaultConfig {
 multiDexEnabled true
}

Option 2. Maven Integration

The MoPub Android SDK comes with a full set of POM files. For depending on these files in Maven:

  1. Run the following command in the mopub-sdk directory:

    $ mvn clean install -DskipTests=true

  2. The mopub-sdk POM includes dependencies on android-support-v4.aar and android-support-annotations.jar. It relies on the presence of the ANDROID_HOME environment variable. You should have this variable set to the root directory of your Android SDK installation.

    • On OS X & Linux this often looks like:

       export ANDROID_HOME "/Users/user/android-sdk-macosx"

      in your .bashrc file.

    • On Windows you can add:

       ANDROID_HOME, C:\<installation location>\android-sdk-windows

      to your environment variables.

  3. Once you’ve installed the MoPub SDK in your local maven repository, you can depend on the project by adding this dependency declaration:

    <dependency>
  <groupId>com.mopub.mobileads</groupId>
  <artifactId>mopub-sdk</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <type>aar</type>
</dependency>

  4. Remember that if you’re using Maven, you also need to have your Android platform libraries installed in your local Maven repository. The Maven Android SDK Deployer is one popular tool for using Maven to build Android projects.

Step 3. Update Your Android Manifest

For deeplink to work properly after Android 11 (API level 30), add the <queries> element to your AndroidManifest.xml. This step is only required if you are integrating MoPub Android SDK v5.17 or older.

<queries>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="*" />
    </intent>
</queries>

Skip the remaining steps if you are integrating MoPub Android SDK v5.10.0 or newer. Relevant permissions and Activities are included in the SDK’s internal AndroidManifest. To remove a specific embedded permission (for example, ACCESS_COARSE_LOCATION), add the following tag to your top level AndroidManifest during integration: <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" tools:node="remove" />

Update your AndroidManifest.xml in order to complete the SDK integration. Add the following permissions and activity declarations according to the bundle you are integrating.

  1. Declare the following permissions:

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

<!-- Optional permissions. Will pass Lat/Lon values when available. Choose either Coarse or Fine -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

    Note that:

    • ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION are only required if you want the device to automatically send the user’s location for targeting.

    • WRITE_EXTERNAL_STORAGE (optional and used for MRAID 2.0 storePicture ads) has been removed starting with MoPub SDK v.5.9.0.

  2. If you are using the full SDK, declare all of the following activities in your <application>. If you are using select ad formats in the modular SDK, declare only the activies that apply.

    <!-- MoPub's consent dialog -->
<activity android:name="com.mopub.common.privacy.ConsentDialogActivity" android:configChanges="keyboardHidden|orientation|screenSize"/>

<!-- All ad formats -->
<activity android:name="com.mopub.common.MoPubBrowser" android:configChanges="keyboardHidden|orientation|screenSize"/>

<!-- Interstitials -->
<activity android:name="com.mopub.mobileads.MoPubActivity" android:configChanges="keyboardHidden|orientation|screenSize"/>
<activity android:name="com.mopub.mobileads.MraidActivity" android:configChanges="keyboardHidden|orientation|screenSize"/>

<!-- Rewarded Ad and Rewarded Playables -->
<activity android:name="com.mopub.mobileads.RewardedMraidActivity" android:configChanges="keyboardHidden|orientation|screenSize"/>
<activity android:name="com.mopub.mobileads.MraidVideoPlayerActivity" android:configChanges="keyboardHidden|orientation|screenSize"/>

  3. Add this tag to your <application> to use Google Play Services:

    <meta-data android:name="com.google.android.gms.version"
      android:value="@integer/google_play_services_version" />

Make sure the com.mopub.mobileads.MraidVideoPlayerActivity is added to your manifest. Without it, video ads will not work correctly (skip this step if you are integrating MoPub Android SDK v5.10.0 or higher).

Step 4. Optionally Use ProGuard

MoPub includes a proguard.txt file in both the mopub-sdk and mopub-sample directories. The contents of these identical files should be included in your Proguard config when using the MoPub SDK in a Proguarded project.

Step 5. Configure Ad Units in Your App

Once you’ve completed the above steps, you can start displaying ads in your application by configuring the ad units as shown in the link below for your ad format:


Last updated August 28, 2021

TWITTER, MOPUB, and the Bird logo are trademarks of Twitter, Inc. or its affiliates. All third party logos and trademarks included are the property of their respective owners.

© 2021 MoPub (a division of Twitter, Inc.)