Getting Started | MoPub Android SDK

What’s new in 5.0
Introduction
Disclosure
Download the MoPub Android SDK
Requirements and Dependencies
(Non-jCenter) Gradle Integration
Maven Integration
Updating your Android Manifest
Add a Network Security Configuration File
ProGuard
Displaying Ads

What’s new in 5.0

Publishers upgrading to the 5.0 MoPub SDK are required to take additional steps. Reference our guides for SDK Initialization and GDPR for more details on how to stay up-to-date and compliant.

Introduction

This document details the process of integrating the MoPub SDK with your Android application. If you have any questions, don’t hesitate to email us at support@mopub.com.

Here are the basic integration steps:

Check out the files from our repository.
Add our SDK (and dependencies) to your project.
Verify the viewability integration through your device logs
Create ad units in your app.

Disclosure

MoPub SDK v4.16 and above integrates technology from our partners Integral Ad Science, Inc. (“IAS”) and Moat, Inc. (“Moat”) in order to support viewability measurement and other proprietary reporting that IAS and Moat provide to their advertiser and publisher clients. You have the option to remove or disable this technology by following the opt-out instructions.

If you do not remove or disable IAS’s and/or Moat’s technology in accordance with these instructions, you agree that IAS’s privacy policy and license and Moat’s privacy policy, terms, and license, respectively, apply to your integration of these partners’ technologies into your application.

Download the MoPub Android SDK

The MoPub SDK is available via:

1. jCenter AAR (Recommended)

The MoPub SDK is available as an AAR via jCenter. To add the mopub-sdk dependency, open your project and update the app module’s build.gradle to have the following repositories and dependencies:

                repositories {
    // ... other project repositories
    jcenter() // includes the MoPub SDK and AVID library
    maven { url "https://s3.amazonaws.com/moat-sdk-builds" }
}

// ...

dependencies {
// ... other project dependencies
    implementation('com.mopub:mopub-sdk:5.4.1@aar') {
        transitive = true
    }
}

              

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:

                repositories {
    // ... other project repositories
    jcenter() // includes the MoPub SDK and AVID library
    maven { url "https://s3.amazonaws.com/moat-sdk-builds" }
}
// ...

dependencies {
    // ... other project dependencies

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

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

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

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

    // For native video. This will automatically also include native static
    implementation('com.mopub:mopub-sdk-native-video:5.4.1@aar') {
        transitive = true
    }
}

              

To continue integration using the mopub-sdk AAR, please continue to Updating your Android Manifest section.

2. Zipped Source

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

MoPub Android SDK.zip

Includes everything you need to serve MoPub ads. No third party ad networks are included.

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

Requirements and Dependencies

Android 4.1 (API Version 16) and up (Updated in 4.12.0)
android-support-v4.jar, r22 (Updated in 3.7.0)
android-support-annotations.jar, r22 (Updated in 3.7.0)
android-support-v7-recyclerview.jar, r22 (Updated in 3.9.0)
MoPub Volley Library (mopub-volley:2.0.0.aar - available on JCenter) (Updated in 5.0.0)
Recommended Google Play Services 11.4.0+

We strongly recommend compiling your app against the Google Play Services Library in order to use the Android Advertising ID instead of the device ID, as required by Google. Failing to correctly use the Android Advertising ID may result in your submission to the Play Store being rejected.

(Non-jCenter) Gradle Integration

Adding as 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, do the following:

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

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

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

              

Open your project’s build.gradle file and add jcenter as a repository and the MoPub SDK as a dependency:

                repositories {
    jcenter() // includes the MoPub SDK and AVID library
    maven { url "https://s3.amazonaws.com/moat-sdk-builds" }
}

// ...

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.0.0.

SDK Modularization

Modularization is also possible from the source code directly. 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-interstitial', ':mopub-sdk:mopub-sdk-rewardedvideo',
        ':mopub-sdk:mopub-sdk-native-static', ':mopub-sdk:mopub-sdk-native-video'

              

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

                repositories {
    jcenter() // includes the MoPub SDK and AVID library
    maven { url "https://s3.amazonaws.com/moat-sdk-builds" }
}
// ...

dependencies {
    // ... other project dependencies

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

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

    // For rewarded videos. 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')

    // For native video. This will automatically also include native static
    implementation project(':mopub-sdk:mopub-sdk-native-video')
}

              

Adding as Compiled .aar

To add the MoPub SDK as an .aar in your project, navigate to the MoPub SDK in your terminal and run the following command gradle mopub-sdk:build. This will build an AAR that bundles the mopub-volley:2.0.0.aar.

Copy the .aar to your library directory: cp build/outputs/aar/mopub-sdk.aar $MY_LIB_DIR where $MY_LIB_DIR is your default library directory.

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

                repositories {
    jcenter() // includes the MoPub SDK and AVID library
    maven { url "https://s3.amazonaws.com/moat-sdk-builds" }
    flatDir {
        dirs '$MY_LIB_DIR'
    }
}

// ...

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

              

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

                defaulConfig {
 multiDexEnable true
}

              

Maven Integration

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

                $ mvn clean install -DskipTests=true

              

inside the mopub-sdk directory.

The mopub-sdk POM includes dependencies on android-support-v4.aar & 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.

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>

              

Remember that if you’re using Maven you’ll 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.

Updating your Android Manifest

Your AndroidManifest.xml will need to be updated in order to complete the SDK integration. Add the following permissions and activity declarations according to the bundle you are integrating.

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"/>

<!-- Optional permissions. Used for MRAID 2.0 storePicture ads -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

              

Note: ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION are only needed if you want the device to automatically send the user’s location for targeting. WRITE_EXTERNAL_STORAGE is optional and only required for MRAID 2.0 storePicture ads.

Declare the following activities in your <application>:

                <!-- 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 Video 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"/>

              

Note: If using the full SDK, you should declare all of the above activities. If using select ad formats in the modular SDK, you should declare only the activies that apply.

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" />

Important Notes

If you’re compiling against APIs below 13, you should exclude screenSize from the manifest entries.
Make sure the com.mopub.mobileads.MraidVideoPlayerActivity is added to your manifest. Without it, video ads will not work correctly.

Add a Network Security Configuration File

Android 9.0 (API 28) blocks cleartext (non-HTTPS) traffic by default, which can prevent ads from serving correctly. To mitigate that, publishers whose apps run on Android 9.0 or above should ensure to add a network security config file. Doing so whitelists cleartext traffic and allows non-HTTPS ads to serve.

In your AndroidManifest.xml file, add the following:

                     <manifest>
     <application
         ...
         android:networkSecurityConfig="@xml/network_security_config"
         ...>
     </application>
 </manifest>

                  

In your network_security_config.xml file, add a base-config that sets cleartextTrafficPermitted to true:

                     <?xml version="1.0" encoding="utf-8"?>
  <network-security-config>
     ...
     <base-config cleartextTrafficPermitted="true">
         <trust-anchors>
             <certificates src="system"/>
         </trust-anchors>
     </base-config>
     <domain-config cleartextTrafficPermitted="false">
         <domain includeSubdomains="true">example.com</domain>
         <domain includeSubdomains="true">cdn.example2.com</domain>
     </domain-config>
     ...
 </network-security-config>

                  

Note: To secure certain domains when base-config allows HTTP traffic, adding domain-config will ensure certain domains will always use HTTPS.

ProGuard

MoPub includes a proguard.cfg 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.

Displaying Ads

Once you’ve completed the above steps, you can start displaying ads in your application by following the simple instructions on the Banner Ad or Interstitial Ad pages.

Last updated December 06, 2018

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.