Android SDK integration instructions

  • Article

This page describes how to integrate the SDK with your project.

For instructions on showing different ad types, see:

This section provides instructions to set up the SDK to display ads in your app.

Requirements

This SDK requires Android 4 or later, and Android SDK version 14 or higher.

In order to show ads, you must have a valid Xandr placement ID. This is a numeric ID that represents a context in an app where ads can be shown.

Tip

  • Google Play To enable the Android Advertising ID (AAID) for frequency capping and mobile app targeting, you must include Google Play Services as a dependency of your app. Xandr's SDK will still function without Google Play Services, but you won't have access to those features.
  • Android Studio and Gradle These instructions assume you are using Android Studio and Gradle. Most of the required AndroidManifest.xml entries (except the location permissions) and ProGuard changes are automatically added to your app. If you are using other build systems, the steps may vary.

Installation

Step 1. Get the SDK

Install via Maven from your build.gradle file as shown below.

Note

  • These are top-level blocks, not part of the buildscript block.
  • The [9,10) notation means that when your app is compiled, the latest version of the SDK in the 9.x release series will be included. When we release a new version of the SDK, all you have to do to get the new version is recompile your app. If you want to include mediation adaptors for other SDKs in your build.gradle, see the section Let us Mediate other Networks of Mediate with Android.

Warning

The compile command is no longer supported by Gradle, it has been replaced with the implementation command.

// Android: Gradle config to install the SDK
repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.appnexus.opensdk:appnexus-sdk:[9,10)'
}

Step 2. Edit app permissions (optional)

Edit your Android manifest to include the following (optional but recommended) permissions:

<!-- Android: XML to include recommended permissions -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

<!-- Add the permissions here... -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  • ACCESS_COARSE_LOCATION (recommended) - Grants the SDK permission to access approximate location based on cell tower.
  • ACCESS_FINE_LOCATION (recommended) - Grants the SDK permission to access a more accurate location based on GPS.

Tip

Location permissions must prompt the user:

In API Level 23 (Marshmallow) and above, you must prompt the user with a dialog at app runtime for either of the location permissions listed above. The SDK can only access location permissions with the user's consent.

For more information, see Request Permissions from the Android documentation.

Although not technically required, the location permissions make it possible for the SDK to send location-based data to advertisers. Sending better location data generally leads to better monetization.

Note

The SDK will never wake up the phone to request the location to be updated; this would take time and battery. Instead, it will use these permissions to access the last known location of the device.

Step 3. Edit ProGuard settings

If your app uses ProGuard, you must edit your ProGuard settings to avoid stripping Google Play out of your app. The SDK doesn't require Google Play to function, but you will lose access to the Android Advertiser ID (AAID), which is used for app targeting and frequency capping. Edit your project's proguard-project.txt file to add the following:

### Proguard settings to support Android Advertiser ID
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient {
    com.google.android.gms.ads.identifier.AdvertisingIdClient$Info getAdvertisingIdInfo(android.content.Context);
}
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient$Info {
    java.lang.String getId();
    boolean isLimitAdTrackingEnabled();
}

Step 4. Set up for mediation (optional)

For instructions on getting set up for mediation, see Mediate with Android.

Implementation note: Forwarding lifecycle callbacks

The SDK allows you to forward lifecycle callbacks for the subclasses of AdView: BannerAdView and InterstitialAdView.

Forwarding lifecycle callbacks is highly recommended for better performance. For anyone mediating AdMob/DFP banners, it is a requirement that they be called, as we need to forward the lifecycle callbacks to the AdMob/DFP banner as required by them. See the code sample below for information about which methods to call, and when.

For more information about activity lifecycles, see Managing the Activity Lifecycle in the Android docs.

    /**
     * To be called by the developer when the fragment/activity's onDestroy() function is called.
     */
    abstract public void activityOnDestroy();

    /**
     * To be called by the developer when the fragment/activity's onPause() function is called.
     */
    abstract public void activityOnPause();

    /**
     * To be called by the developer when the fragment/activity's onResume() function is called.
     */
    abstract public void activityOnResume();