Get Started

Android – Getting Started

This document details the process of integrating the MoPub SDK with your Android application. If you have any questions, don’t hesitate to reach out to your Account team or email us at [email protected].

Here are the basic integration steps:

  1. Check out the files from our repository.
  2.  Add our SDK (and dependencies) to your project.
  3. Create ad units in your app.

Download the MoPub Android SDK

The MoPub SDK is available via:

        • jCenter AAR (Recommended)jCenter AARThe MoPub SDK is available as an AAR via jCenter. To add the mopub-sdk dependency, open your project’s build.gradle and update the repositories and dependencies blocks as follows: 
          repositories {
    // ... other project repositories
    jcenter()
}

// ...

dependencies {
    // ... other project dependencies
    compile('com.mopub:mopub-sdk:4.9.0@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 each component that you want in your `build.gradle` file as follows: 
          repositories {
        // ... other project repositories
        jcenter()
    }
    // ...

    dependencies {
        // ... other project dependencies

        // For banners
        compile('com.mopub:mopub-sdk-banner:4.9.0@aar') {
            transitive = true
        }
        
        // For interstitials
        compile('com.mopub:mopub-sdk-interstitial:4.9.0@aar') {
            transitive = true
        }

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

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

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

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

        • Zipped SourceThe MoPub SDK is also distributed as zipped source code that you can include in your application. Includes everything you need to serve MoPub ads HTML and MRAID ads. No third party ad networks are included:MoPub Android SDK.zip
        • Cloned GitHub repositoryAlternatively, 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 2.3.1 (API Version 9) and up
    • 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-1.1.0.jar – available on JCenter) (Updated in 3.6.0)
    • Recommended Google Play Services  9.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()
}

// ...

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

This is required in order to resolve the MoPub SDK’s compile time dependency on ‘com.mopub.volley:mopub-volley:1.1.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-base’, ‘:mopub-sdk-banner’,
‘:mopub-sdk-interstitial’, ‘:mopub-sdk-rewardedvideo’,
‘:mopub-sdk-native-static’, ‘:mopub-sdk-native-video’

repositories {
        jcenter()
    }
    // ...

    dependencies {
        // ... other project dependencies

        // For banners
        compile project(':mopub-sdk-banner')
        
        // For interstitials
        compile project(':mopub-sdk-interstitial')

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

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

        // For native video. This will automatically also include native static
        compile project(':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-1.1.0.jar.

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()
  flatDir {
    dirs '$MY_LIB_DIR'
  }
}

// ...

dependencies {
  compile(name:'mopub-sdk', ext:'aar')
  compile 'com.mopub.volley:mopub-volley:1.1.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.

Base Bundle/AAR:

Declare the following permissions:

  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <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:

  <activity android:name="com.mopub.mobileads.MoPubActivity" android:configChanges="keyboardHidden|orientation|screenSize"/>
  <activity android:name="com.mopub.mobileads.MraidActivity" android:configChanges="keyboardHidden|orientation|screenSize"/>
  <activity android:name="com.mopub.common.MoPubBrowser" android:configChanges="keyboardHidden|orientation|screenSize"/>
<activity android:name="com.mopub.mobileads.MraidVideoPlayerActivity" android:configChanges="keyboardHidden|orientation|screenSize"/>

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

1. If you’re compiling against APIs below 13, you should exclude ‘screenSize‘ from the manifest entries.

2. Make sure the ‘com.mopub.mobileads.MraidVideoPlayerActivity‘ is added to your manifest. Without it, video ads will not work correctly.

Displaying Ads

Once you’ve completed the above steps, you can start displaying ads in your application by following our instructions for Banners, Interstitials, Native, or Rewarded Video.