Setup

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

Prerequisites

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 Mediation Networks. 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 on Mediation Networks. 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.

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, DFP 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 in the PublisherAdRequest. In this example, the location is set before loading the ad request:

Location location = new Location("");
// New York
location.setLatitude(40.764316);
location.setLongitude(-73.977245);
location.setAccuracy(100);

PublisherAdRequest request = new PublisherAdRequest.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.

Demographic targeting

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

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

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

Child-directed treatment in mediation

DFP Mediation facilitates compliance with the Children's Online Privacy Protection Act (COPPA).

Set tagForChildDirectedTreatment(true) in the Google Mobile Ads SDK to indicate whether you want your content treated as child-directed for the purposes of COPPA or not. Google makes this signal available to third-party ad networks in Mediation to facilitate COPPA compliance. See Tag an ad request for child-directed treatment (TFCD) for more information.

DFP simply serves as a platform. The advertising relationship is between the mobile app developer and the third-party ad network, so it's the developer's responsibility to ensure that each third-party ad network serves ads that treat the developer's content as child-directed for purposes of COPPA.

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.

v1

You can pass extra parameters to specific mediation networks by using the addNetworkExtras() method of the AdRequest. The addNetworkExtras() method receives an instance of a class that implements NetworkExtras.

Each network defines its own extras class. The following table shows the names of these classes for some of the networks.

Ad Network Additional Parameters Class
Millennial Media com.google.ads.mediation.millennial.MillennialAdapterExtras
InMobi com.google.ads.mediation.inmobi.InMobiAdapterExtras

For example, both Millennial Media and InMobi allow specifying the income of the user to provide more relevant ads. In order to make the mediation framework pass an income when requesting an ad from these networks, you could use the following code:

import com.google.android.gms.ads.doubleclick.PublisherAdRequest;
import com.google.android.gms.ads.doubleclick.PublisherAdView;
import com.google.ads.mediation.inmobi.InMobiAdapterExtras;
import com.google.ads.mediation.millennial.MillennialAdapterExtras;
/* … */

    /* Set parameters common to all networks in ad request. */

    // 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.
    PublisherAdRequest adRequest = new PublisherAdRequest.Builder()
        .addNetworkExtras(millennialExtras)
        .addNetworkExtras(inMobiExtras)
        .build();

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

You can pass extra parameters to specific mediation networks by using the addNetworkExtrasBundle() method on PublisherAdRequest.Builder. Pass the adapter class to which you want to send parameters, and a Bundle of values for the adapter to consume.

In most cases, if an adapter supports extra parameters it has either constants to represent appropriate keys for the bundle or some method to help generate a valid bundle to pass to their network.

Custom Rendering mediation

The Mobile Ads SDK allows you to use mediation to load native ads as well as banner and interstitial ads. On receiving one of these ads from a mediated network, the Mobile Ads SDK maps its assets to one of its two system-defined native ad formats (app install or content ad) before returning it to you. This means that, in general, you can write a single section of code to handle displaying native ad assets from multiple networks.

Because native ads provide you so much freedom, there are a few extra things to consider when using mediation, such as how to handle optional and extra assets, which formats to request, and the importance of ensuring the native ad presentation conforms to the mediated networks' policies.

Request both system-defined formats

The Mobile Ads SDK allows you to specify a preference for app install ads, content ads, or both for each request. However, not every mediated network offers both of these formats, and some are unable to filter by format. In order to make sure that ad requests have the best chance of being filled, it's highly recommended that apps request both formats when loading native ads and include rendering code that can display either one.

Optional assets

Guidelines for programmatic native ads using custom rendering lists the assets that go with each system-defined native ad format available from the Mobile Ads SDK. When using mediation, it's particularly important to be aware that some of these fields are included in every native ad, while others are optional. For example, some mediated SDKs may include a price asset with their app install ads while others do not, and so on.

It's a good idea to check the list of assets for each system-defined native ad format and make sure your app properly accounts for those that aren't always included. For example, here's a code snippet from an onAppInstallAdLoaded() method that checks to see if the price asset is present in a NativeAppInstallAd object and shows or hides the corresponding asset view as appropriate:

if (nativeAppInstallAd.getPrice() == null) {
    adView.getPriceView().setVisibility(View.INVISIBLE);
} else {
    adView.getPriceView().setVisibility(View.VISIBLE);
    ((TextView) adView.getPriceView()).setText(nativeAppInstallAd.getPrice());
}

Extra assets

Some mediated networks may provide assets beyond those normally included by the Mobile Ads SDK (such as an image asset for an AdChoices icon). In order to make sure these additional assets are available to you, the SDK exposes them in a Bundle via the getExtras() method.

For example, if a mediated network included a "category" string asset in its app install ads, the code to retrieve the asset would look like this:

St ring categoryString = ""; Bundle extras = nativeAppInstallAd.getExtras(); if (extras.containsKey("CATEGORY_KEY")) { categoryString = extras.getString("CATEGORY_KEY")); } ```

The names of the keys used to retrieve assets from the Bundle vary by ad network ("CATEGORY_KEY" is just an example). Check the documentation provided with the adapter for details.

Native ad options

The Mobile Ads SDK provides the NativeAdOptions object so that you can specify preferences for how native ads should be delivered. This includes things like the automatic downloading of images, preferred orientation, and other details. This information is given to mediated networks as part of the mediation process. However, not every ad network's SDK is able to abide by all of these options. We recommend that you rigorously test your applications with mediated ads from each network to ensure stability.

One example of this is the shouldReturnUrlsForImageAssets option. Normally, if this is set to true, the Mobile Ads SDK does not automatically download image assets for the ads, and instead returns just the URLs that point to them. If a mediated SDK always downloads images automatically, though, it would be wasteful for the adapter to discard them (only to have the application download them again itself). So in this situation, the adapter always returns image assets regardless of the value of shouldReturnUrlsForImageAssets.

Check the documentation provided with individual mediation adapters for details on which options are supported by that network.

Native ad presentation policy

Each ad network has its own policies. When using mediation, it's important to remember that your app still needs to abide by the polices of the mediated network that provided the ad.

AdChoices

The Mobile Ads SDK automatically places the AdChoices logo for you. Mediation adapters are also responsible for placing the AdChoices logo if applicable, so you don't need to take any action to display an AdChoices asset in their app.

FAQ

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 add network adapters and SDKs for all ad networks you're mediating.
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

Send feedback about...

SDK for DFP Users on Android
Need help? Visit our support page.