Mediation

This guide is intended for publishers that are interested in using Google Mobile Ads mediation. We'll walk through getting a mediation adapter set up with your current Android app and setting up additional request parameters.

Prerequisites

• An Android app with Google Mobile Ads SDK integrated
• An account set up with one or more of the supported mediation networks
• An AdMob account and an ad unit configured with mediation line items

Helpful primers

The following Help Center articles provide a lot of information:

• About AdMob Mediation
• Set up AdMob Mediation
• Optimize AdMob Network

If you haven't integrated the Google Mobile Ads SDK with your app yet, see Get Started.

Add mediation adapters to your project

Include network adapters and SDKs

Once you know which networks you want to serve ads from, you can download the SDK and adapter for those networks from the mediation networks page. Some of these SDKs already include a Google Mobile Ads adapter.

In Android Studio, include the JAR files in your project's libs folder. Make sure that your build.gradle file includes the following:

compile fileTree(dir: 'libs', include: ['*.jar'])

In Eclipse, include the JAR files in your project's libs folder. Right-click on your project and select Properties. Then add all the JAR files to your Java Build Path.

Configure the AndroidManifest.xml file

Add entries to your AndroidManifest.xml file as required by each ad network you intend to use. Instructions from each network can be found from the mediation networks page. Follow instructions related to modifying your AndroidManifest.xml file.

Your app doesn't need to call any ad networks—the Google Mobile Ads SDK calls the third-party ad network adapters to fetch third-party ads on your behalf. If you don't wish to specify any additional request parameters, then you're done! Otherwise, read on to learn how to provide more information to the mediating ad networks.

Configure ProGuard settings

If you use ProGuard, you need to configure it to avoid obfuscating some of the code used in the mediation process. AdMob mediation needs two classes to maintain their original names in your final APK: AdUrlAdapter and AdMobAdapter. If either is renamed by ProGuard, it can cause the SDK to incorrectly return "no fill" responses for the AdMob demand in your mediated ad units.

To make sure those classes are left unchanged by ProGuard, just add these options to your ProGuard configuration file:

-keep class com.google.ads.mediation.admob.AdMobAdapter {
    *;
}

-keep class com.google.ads.mediation.AdUrlAdapter {
    *;
}

Initialize your ad object with an Activity instance

In the constructor for a new ad object (for example, AdView), you must pass in an object of type Context. This Context is passed on to other ad networks when using mediation. Some ad networks require a more restrictive Context that is of type Activity and may not be able to serve ads without an Activity instance. Therefore, we recommend passing in an Activity instance when initializing ad objects to ensure a consistent experience with your mediated ad networks.

Specify additional request parameters (optional)

You can optionally add targeting information (such as location, birthday, gender, and COPPA preferences) that can be used by networks to serve more finely targeted ads.

Location targeting

If a user has granted your app location permissions, AdMob automatically passes this location data to the SDK. The SDK uses this data to improve ad targeting without requiring any code changes in your app. You can, of course, enable or disable location data for ads.

Autopopulated location information is not forwarded to mediation networks and autolocation may be disabled entirely. Therefore, the SDK provides the ability to set location manually. You can specify location-targeting information in the AdRequest as follows:

AdRequest request = new AdRequest.Builder()
    .setLocation(location)
    .build();

where the user's location is obtained by a suitable method.

Out of respect for user privacy, Google asks that you specify location only if that information is already being used by your app.

Besides location, you can also target on birthday and gender, as well as set COPPA tags.

Demographic targeting

You can optionally add demographic targeting information such as user's gender and birthday to your AdRequest. This information can be used by networks to serve more finely targeted ads.

We provide methods for setting gender and birthday. These are passed along to all networks that accept them. Here is an example:

AdRequest request = new AdRequest.Builder()
    .setGender(AdRequest.GENDER_FEMALE)
    .setBirthday(new GregorianCalendar(1985, 1, 1).getTime())  // January 1, 1985
    .build();

Network-specific parameters

Some networks also support other request parameters that are specific to their network. Refer to the "v1" or "v2" instructions below to learn how to provide these other parameters to the networks. If you are unsure if the adapter is v1 or v2, try calling addNetworkExtrasBundle() with the adapter class (as detailed in v2 below). If the adapter compiles, then it's a v2 adapter; otherwise, it's a v1 adapter. You can use both v1 and v2 adapters in the same app.

import com.google.android.gms.ads.AdRequest;
import com.google.android.gms.ads.AdView;
import com.google.ads.mediation.inmobi.InMobiAdapterExtras;
import com.google.ads.mediation.millennial.MillennialAdapterExtras;

/* … */

    /* Set parameters common to all networks in 'adRequest'. */

    // Millennial Media extra parameters.
    MillennialAdapterExtras millennialExtras = new MillennialAdapterExtras();
    millennialExtras.setIncomeInUsDollars(65000);

    // InMobi extra parameters.
    InMobiAdapterExtras inMobiExtras = new InMobiAdapterExtras();
    inMobiExtras.setIncome(65000);

    // Create the ad request with these extra parameters.
    AdRequest adRequest = new AdRequest.Builder()
        .addNetworkExtras(millennialExtras)
        .addNetworkExtras(inMobiExtras)
        .build();

    // Finally, request the ad.
    adView.loadAd(adRequest);

Bundle bundle = new Bundle();
bundle.putString("color_bg", "0000FF");
AdRequest adRequest = new AdRequest.Builder()
    .addNetworkExtrasBundle(SampleAdapter.class, bundle)
    .build();

Request agent (for third-party libraries)

We recommend that third-party libraries that reference the Mobile Ads SDK call the setRequestAgent() method to denote the platform from which the ad request originated. For example, if a third-party ad network called "Cool Ad Network" mediates requests to the Mobile Ads SDK and wants to tag its requests for Analytics purposes, it can do so like this:

AdRequest request = new AdRequest.Builder()
    .setRequestAgent("Cool Ad Network")
    .build();

FAQ

What if I want to mediate with a network, but there is no supported adapter for it?

You can write your own mediation adapters using custom events.

Do Ad Listeners still work with mediation?

Yes, they still work with all mediation networks.

Do v1 mediation adapters work with Google Play services?

Yes. The Mobile Ads SDK included in Google Play services is designed to maintain backwards compatibility with our v1 mediation adapters.

Suppose I add a new network to my mediation configuration for the next version of my app. How does that affect the current version of my app that doesn't include this network?

The SDK detects that the adapter isn't there and fails gracefully; the request goes to the next network in the mediation waterfall.

What does the "Could not instantiate mediation adapter: x.y.z.SomeAdapter" error message mean?

Your project is likely missing the adapter library that contains this class. You need to include network adapters and SDKs for all ad networks you're mediating.