Note

If using the Fabric IDE plugins, you can skip this article. The Fabric plugin will walk you through setting up the MoPub SDK.

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:

1. Check out the files from our repository.

2. Add our SDK to your Eclipse project.

3. Create ad units in your app.

Download the MoPub Android SDK

The MoPub SDK is distributed as source code that you must include in your application. MoPub provides two prepackaged archives of source code:

• MoPub Android Full SDK.zip
  Includes everything you need to serve HTML and MRAID MoPub advertisements *and* built-in support for the Millennial Media ad network - including the required third party binaries.
• MoPub Android Base SDK.zip
  Includes everything you need to serve HTML and MRAID MoPub advertisements. No third party ad networks are included.

Requirements and Dependencies

The MoPub SDK requires Android version 2.3 or greater. It also depends on the Android v4 support library and 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.

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 the MoPub SDK as a dependency:

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

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

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 ensure your library directory is added as a repository and the MoPub SDK is added as a dependency:

repositories {
  flatDir {
    dirs '$MY_LIB_DIR'
  }
}

...

dependencies {
  compile(name:'mopub-sdk', ext:'aar')
}

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 the Android v4 Support Library and 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:\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>jar</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.

Eclipse Integration

The MoPub Android SDK archive contains a library project called `mopub-sdk`.

1. Import the mopub-sdk archive into your workspace by clicking File > Import… and choosing Existing Projects into Workspace.

2. Click the Select Archive File button then click Browse…

3. Select the mopub-sdk archive file. Then, click Open.

4. …then Finish.

Adding the SDK to Your Project

1. Go to the Eclipse Package Explorer, right-click your project folder and select Properties.

2. Choose Android from the sidebar.

3. Click Add… under the Library section, and select the mopub-sdk project.

Adding the Support Library to Your Project

Follow the instructions on the Android Developer Site for setting up the support library v4 using Eclipse: https://developer.android.com/tools/support-library/setup.html

Adding Google Play Sevices

Follow the instructions on the Android Developer Site for setting up Google Play Services. We recommend always using the latest version of Google Play Services. http://developer.android.com/google/play-services/setup.html

Adding Ad Network Libraries to Your Project

If you are using the full bundle you will need to add the Jar files for the supported ad networks to the build path of your project.

1. Go to the Eclipse Package Explorer, right-click your project folder and select Properties.

2. Choose Java Build Path from the sidebar.

3. Click Add Jars, open the mopub-sdk/libs section of the tree and add all of the files it contains.

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.

Full Bundle:

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

Declare the following activities:

  <activity android:name="com.mopub.mobileads.MoPubActivity" android:configChanges="keyboardHidden|orientation"/>
  <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"/>
  <activity android:name="com.google.android.gms.ads.AdActivity" android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|uiMode|screenSize|smallestScreenSize" />
  <activity android:name="com.millennialmedia.android.MMActivity" android:theme="@android:style/Theme.Translucent.NoTitleBar" android:configChanges="keyboardHidden|orientation|keyboard" />
  <activity android:name="com.millennialmedia.android.VideoPlayer" android:configChanges="keyboardHidden|orientation|keyboard" />

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.

3. If you’re updating to Version 2.0, you should rename `com.mopub.mobileads.MraidBrowser` Activity to `com.mopub.common.MoPubBrowser` in your manifest.

Base Bundle:

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

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.

3. If you’re updating to Version 2.0, you should rename `com.mopub.mobileads.MraidBrowser` Activity to `com.mopub.common.MoPubBrowser` in your manifest.

Using the GitHub Repository Source Code

While the bundled zips are the preferred method to install the MoPub SDK you can, instead, clone the git repository:

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

The installation instructions are similar to the ones outlined above for the zip archives. To install the base SDK you must import the `mopub-sdk` folder as an existing project into the workspace. This is equivalent to using the `mopub-android-base-sdk.zip` bundle described above. If you plan to use a third-party ad network, you will need to integrate its SDK natively. Detailed instructions for doing so can be found here: Integrating Third Party Ad Networks.

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.