Google Mobile Ads SDK

DoubleClick for Publishers (DFP) Network Mediation

See this article for a walk-through of what mediation is and how to set it up in DFP. Then, continue reading this page for instructions on how to add mediation code into your app.

Mediation is available for iOS and Android.

Android (Google Play)
  1. Adding the Mediation SDK to your project
    1. 1. Integrate DFP ads
    2. 2. Add network adapters and SDKs
    3. 3. Configure ad networks in AndroidManifest.xml
  1. Optional setup
    1. 4. Specify additional request parametersoptional
    2. 5. Set up an ad listeneroptional
    3. 6. Implement custom eventsoptional

Adding the Mediation SDK to your project

1. Integrate DFP ads

Set up SDK Mediation creatives in the DFP UI; refer to the article Add a new mobile creative for detailed instructions. Afterwards, proceed to integrating DFP banner or interstitial ads into your application.

2. Add network adapters and SDKs

You're now ready to download and add to your project the adapters and SDKs of all the ad networks you'd like to serve ads from (AdMob is already included in the Mediation SDK). You can find links to them on the ad network mediation page.

To add the downloaded network adapters/SDKs in Eclipse, right click on your project and select Properties. Then add all the JAR files to your Java Build Path.

Note: You may consider integrating adapters and SDKs from networks that you're not currently using but might use in the future. If you do this, you'll be able to start serving ads from these networks simply by making a configuration change on mediation.admob.com (without requiring a code change to your app). Weigh this against the increase in app binary size that each additional SDK will add.

3. Configure ad networks in AndroidManifest.xml

You now need to add entries to your AndroidManifest.xml as required by each ad network you intend to use. Instructions from each network can be found from the ad network mediation page. Follow the parts of these instructions related to modifying your AndroidManifest.xml file.

Note that you only need to modify your manifest, and that there is no need to follow the networks' instructions for creating ad views or setting up listeners. The Google Mobile Ads SDK will invoke each ad network's adapters and SDKs as necessary to create ads. Further below you'll see how to set up Mediation listeners that notify you of ad events for all of your networks.

Back to top

Optional setup

4. (optional) Specify additional request parameters

You can optionally add the user's location, gender, and birthday to your PublisherAdRequest. These are not required, but can be used by networks to serve more finely targeted ads. We provide methods for setting birthday and location, and a property for setting gender. These will be passed along to all networks that accept them.

Here is an example:

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

Some networks also support other request parameters that are specific to their network. You can specify these by using the addNetworkExtras() method of the PublisherAdRequest. The addNetworkExtras() method receives an instance of one of the "extras" classes below.

Each network defines its own extras class. The following table shows the names of these classes for some of the networks. Consult the Javadocs for each class and the ad network's SDK documentation for more details on each class.

Ad Network Additional-parameters class
Google AdMob com.google.android.gms.ads.mediation.admob.AdMobExtras
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;

/* … */

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

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

Back to top

5. (optional) Set up an ad listener

To be notified of ad lifecycle events like impressions, you can create a class that extends com.google.android.gms.ads.AdListener. This listener will automatically notify you about events from all the networks you're mediating. For example, impressions from any ad network will be reported through the onAdLoaded method. See the Banner Ads guide for more details on AdListener.

6. (optional) Implement custom events

Custom Events are a way to serve ads from your own ad server, from an ad network that is not featured in AdMob Mediation, or to invoke any other code of your choice.

To create a Custom Event, define a class that implements CustomEventBanner.

A Custom Event must report back to CustomEventBannerListener when it successfully receives an ad or when it fails to receive an ad. To do this, call the appropriate listener method (as shown below). Failing to do this will stop the mediation waterfall from running correctly.

Preferably, your Custom Event should also report clicks and the outcome of the click action (presenting a full-screen modal or leaving the app) by notifying the CustomEventBannerListener. This will allow click stats to be counted in your reporting and will allow any event listeners you've set up to work properly.

We instantiate your CustomEventBanner and set the CustomEventBannerListener for you at runtime—there's no need to instantiate these classes yourself.

Here is an example Custom Event:

public class CustomAd implements CustomEventBanner {
  @Override
  public void requestBannerAd(final CustomEventBannerListener listener,
                              final Activity activity,
                              String label,
                              String serverParameter,
                              AdSize adSize,
                              MediationAdRequest request,
                              Object customEventExtra) {
    ImageView imageView = new ImageView(activity);
    imageView.setImageResource(R.drawable.floodit_ad);
    imageView.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        try {
          listener.onClick();
          listener.onPresentScreen();
          listener.onLeaveApplication();
          Intent intent = new Intent(Intent.ACTION_VIEW,
                                     Uri.parse("market://details?id=com.labpixies.flood"));
          activity.startActivity(intent);
        } catch (Throwable t) {
          // Something went wrong, oh well.
        }
      }
    });
    listener.onReceivedAd(imageView);
/* This custom event will always succeed, so we haven't called the onFailedToReceiveAd method */
  }

  @Override
  public void destroy() {
    // Clean up custom event variables.
  }
}

Refer to the CustomEventBanner and CustomEventBannerListener Javadocs for further details.

Your Custom Event can call methods of the ad request to get access to request parameters like age or gender. See the MediationAdRequest Javadocs for further details on this.

To create an interstitial Custom Event that takes over the entire screen, instead of a Custom Event that lives inside a banner view, use CustomEventInterstitial instead of CustomEventBanner (see the CustomEventInterstitial and CustomEventInterstitialListener Javadocs for details).

Android (6.4.1 and earlier SDKs)
  1. Adding the Mediation SDK to your project
    1. 1. Integrate DFP ads
    2. 2. Add network adapters and SDKs
    3. 3. Configure ad networks in AndroidManifest.xml
  1. Optional setup
    1. 4. Specify additional request parametersoptional
    2. 5. Set up an ad listeneroptional
    3. 6. Implement custom eventsoptional

Adding the Mediation SDK to your project

1. Integrate DFP ads

Set up SDK Mediation creatives in the DFP UI; refer to the article Add a new mobile creative for detailed instructions. Afterwards, proceed to integrating DFP banner or interstitial ads into your application.

2. Add network adapters and SDKs

You're now ready to download and add to your project the adapters and SDKs of all the ad networks you'd like to serve ads from (AdMob is already included in the Mediation SDK). You can find links to them on the ad network mediation page.

To add the downloaded network adapters/SDKs in Eclipse, right click on your project and select Properties. Then add all the JAR files to your Java Build Path.

Note: You may consider integrating adapters and SDKs from networks that you’re not currently using but might use in the future. If you do this, you’ll be able to start serving ads from these networks simply by making a configuration change on mediation.admob.com (without requiring a code change to your app). Weigh this against the increase in app binary size that each additional SDK will add.

3. Configure ad networks in AndroidManifest.xml

You now need to add entries to your AndroidManifest.xml as required by each ad network you intend to use. Instructions from each network can be found from the ad network mediation page. Follow the parts of these instructions related to modifying your AndroidManifest.xml file.

Note that you only need to modify your manifest, and that there is no need to follow the networks' instructions for creating ad views or setting up listeners. The Google Mobile Ads SDK will invoke each ad network's adapters and SDKs as necessary to create ads. Further below you'll see how to set up Mediation listeners that notify you of ad events for all of your networks.

Back to top

Optional setup

4. (optional) Specify additional request parameters

You can optionally add the user's location, gender, and birthday to your AdRequest. These are not required, but can be used by networks to serve more finely targeted ads. We provide methods for setting birthday and location, and a property for setting gender. These will be passed along to all networks that accept them.

Here is an example:

request.setGender(AdRequest.Gender.FEMALE);
request.setLocation(location);
request.setBirthday(new Date(85,0,1)); /*January 1, 1985*/

Some networks also support other request parameters that are specific to their network. You can specify these by using the setNetworkExtras() method of the AdRequest. The setNetworkExtras() method receives an instance of one of the "extras" classes below.

Each network defines its own extras class. The following table shows the names of these classes for some of the networks. Consult the Javadoc for each class and the ad network's SDK documentation for more details on each class.

Ad Network Additional-parameters class
Google AdMob com.google.ads.mediation.admob.AdMobAdapterExtras
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.ads.AdRequest;
import com.google.ads.doubleclick.DfpAdView;
import com.google.ads.mediation.inmobi.InMobiAdapterExtras;
import com.google.ads.mediation.millennial.MillennialAdapterExtras;

/* … */

    AdRequest adRequest = new AdRequest();

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

    // Millennial Media extra parameters.
    MillennialAdapterExtras millennialExtras = new MillennialAdapterExtras();
    millennialExtras.setIncomeInUsDollars(65000);
    adRequest.setNetworkExtras(millennialExtras);
  
    // InMobi extra parameters.
    InMobiAdapterExtras inMobiExtras = new InMobiAdapterExtras();
    inMobiExtras.setIncome(65000);
    adRequest.setNetworkExtras(inMobiExtras);

    /* Similarly set extra parameters for other networks. */

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

Back to top

5. (optional) Set up an ad listener

To be notified of ad lifecycle events like impressions, you can implement a com.google.ads.AdListener. When using mediation, this listener will automatically notify you about events from all the networks you're mediating. For example, impressions from any ad network will be reported through the com.google.ads.AdListener method onReceiveAd.

6. (optional) Implement custom events

Custom Events are a way to serve ads from your own ad server, from an ad network that is not featured in AdMob Mediation, or to invoke any other code of your choice.

To create a Custom Event, define a class that implements CustomEventBanner.

A Custom Event must report back to CustomEventBannerListener when it successfully receives an ad or when it fails to receive an ad. To do this, call the appropriate listener method (as shown below). Failing to do this will stop the mediation waterfall from running correctly.

Preferably, your Custom Event should also report clicks and the outcome of the click action (presenting a full-screen modal or leaving the app) by notifying the CustomEventBannerListener. This will allow click stats to be counted in your reporting and will allow any event listeners you've set up to work properly.

We instantiate your CustomEventBanner and set the CustomEventBannerListener for you at runtime—there's no need to instantiate these classes yourself.

Here is an example Custom Event:

public class CustomAd implements CustomEventBanner {
  @Override
  public void requestBannerAd(final CustomEventBannerListener listener,
                              final Activity activity,
                              String label,
                              String serverParameter,
                              AdSize adSize,
                              MediationAdRequest request,
                              Object customEventExtra) {
    ImageView imageView = new ImageView(activity);
    imageView.setImageResource(R.drawable.floodit_ad);
    imageView.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        try {
          listener.onClick();
          listener.onPresentScreen();
          listener.onLeaveApplication();
          Intent intent = new Intent(Intent.ACTION_VIEW,
                                     Uri.parse("market://details?id=com.labpixies.flood"));
          activity.startActivity(intent);
        } catch (Throwable t) {
          // Something went wrong, oh well.
        }
      }
    });
    listener.onReceivedAd(imageView);
/* This custom event will always succeed, so we haven't called the onFailedToReceiveAd method */
  }

  @Override
  public void destroy() {
    // Clean up custom event variables.
  }
}

Refer to the CustomEventBanner and CustomEventBannerListener Javadocs for further details.

Your Custom Event can call methods of the ad request to get access to request parameters like age or gender. See the MediationAdRequest Javadocs for further details on this.

To create an interstitial Custom Event that takes over the entire screen, instead of a Custom Event that lives inside a banner view, use CustomEventInterstitial instead of CustomEventBanner (see the CustomEventInterstitial and CustomEventInterstitialListener Javadocs for details).

iOS
  1. Adding the Mediation SDK to your project
    1. 1. Integrate DFP ads
    2. 2. Add network adapters and SDKs
    3. 3. Add required linker flags
    4. 4. Include network configurations
  1. Optional setup
    1. 5. Specify additional request parametersoptional
    2. 6. Set up event notificationoptional
    3. 7. Implement custom eventsoptional
    4. 8. Check the value of adNetworkClassNameoptional

Adding the Mediation SDK to your project

1. Integrate DFP ads

Set up SDK Mediation creatives in the DFP UI; refer to the article Add a new mobile creative for detailed instructions. Afterwards, proceed to integrating DFP banner or interstitial ads into your application.

2. Add network adapters and SDKs

You're now ready to download and add to your project the adapters and SDKs of all the ad networks you'd like to serve ads from. You can find links to them on the ad network mediation page.

To add the downloaded network adapters/SDKs in Xcode, right click on your project and click Add Files to project...

Note: You may consider integrating adapters and SDKs from networks that you're not currently using but might use in the future. If you do this, you'll be able to start serving ads from these networks simply by making configuration changes in your DFP account without requiring a code change to your app. Weigh this against the increase in app binary size that each additional SDK will add.

3. Add required linker flags

You now need to add -ObjC to the Other Linker Flags of your application target's build setting:

  1. In Xcode's project navigator, press the blue top-level project icon.
  2. Click on your target, then the Build Settings tab.
  3. Under Other Linker Flags, add -ObjC to both Debug and Release.

4. Include network configurations

You need to include any frameworks, compiler flags, or linker flags that your chosen networks require. For your convenience, the ad network mediation page has links to each network's instructions.

There is no need to write additional code to create ad views from each ad network. The Google Mediation SDK will invoke each ad network's adapters and SDKs as necessary to create ads. Further below you'll see how to set up Mediation listeners that notify you of ad events for all of your networks.

Back to top

Optional setup

5. (optional) Specify additional request parameters

You can optionally add the user's location, gender, and birthday to your requests. These are not required, but can be used by networks to serve more finely targeted ads. We provide methods for setting birthday and location, and a property for setting gender. These will be passed along to all networks that accept them.

Here is an example:

- (void)setBirthdayWithMonth:(NSInteger)m day:(NSInteger)d year:(NSInteger)y;

- (void)setLocationWithLatitude:(CGFloat)latitude longitude:(CGFloat)longitude
                       accuracy:(CGFloat)accuracyInMeters;

@property (nonatomic, assign) GADGender gender;

typedef enum {
  kGADGenderUnknown,
  kGADGenderMale,
  kGADGenderFemale
} GADGender;

Some networks accept other parameters like user income or banner color. Ad networks will be adding support for these specific parameters in their mediation adapters over time, but no network-specific parameters are currently able to be passed.

6. (optional) Set up event notification

To be notified of ad lifecycle events like impressions, you can implement a GADBannerViewDelegate. When using mediation, this delegate will automatically be notified of events from all the networks you're mediating. For example, impressions from any ad network will be reported through the GADBannerViewDelegate method adViewDidReceiveAd.

7. (optional) Implement custom events

Custom Events are a way to serve ads from your own ad server, from an ad network that is not featured in AdMob Mediation, or to invoke any other code of your choice.

To create a Custom Event, define a class that implements GADCustomEventBanner.

A Custom Event must report back to the GADCustomEventBannerDelegate when it successfully receives an ad or when it fails to receive an ad. To do this, call the appropriate delegate method (as shown below). Failing to do this will stop the mediation waterfall from running correctly.

Preferably, your Custom Event should also report clicks and the outcome of the click action (presenting a full-screen modal or leaving the app) by notifying the delegate. This will allow click stats to be counted in your reporting and will allow any event listeners you've set up to work properly.

We instantiate your GADCustomEventBanner and set the GADCustomEventBannerDelegate for you at runtime—there's no need to instantiate these classes yourself.

Here is an example Custom Event:

@implementation MyCustomEventBanner

// Will be set by the SDK.
@synthesize delegate = delegate_;

#pragma mark -
#pragma mark GADCustomEventBanner

- (void)requestBannerAd:(GADAdSize)adSize
              parameter:(NSString *)serverParameter
                  label:(NSString *)serverLabel
                request:(GADCustomEventRequest *)request  {

  // TODO: Use the parameters and self.delegate to make a banner request to your
  // ad network. Remember to set this class to be your banner’s delegate.
}

#pragma mark -
#pragma mark MyBanner Callbacks

- (void)adViewDidReceiveAd:(MyBanner *)view {
  [self.delegate customEventBanner:self didReceiveAd:view];
}

- (void)adView:(MyBanner *)view
    didFailToReceiveAdWithError:(NSError *)error {
  [self.delegate customEventBanner:self didFailAd:error];
}

- (void)adViewWillPresentScreen:(MyBanner *)adView {
  [self.delegate customEventBannerWillPresentModal:self];
}

- (void)adViewWillDismissScreen:(MyBanner *)adView {
  [self.delegate customEventBannerWillDismissModal:self];
}

- (void)adViewDidDismissScreen:(MyBanner *)adView {
  [self.delegate customEventBannerDidDismissModal:self];
}

- (void)adViewWillLeaveApplication:(MyBanner *)adView {
  [self.delegate customEventBannerWillLeaveApplication:self];
}

@end

Refer to the GADCustomEventBanner.h and GADCustomEventBannerDelegate.h files for further details.

Your Custom Event can call methods of the ad request to get access to request parameters like age or gender. See GADCustomEventRequest.h for further details on this.

To create an interstitial Custom Event that takes over the entire screen, instead of a Custom Event that lives inside a banner view, use GADCustomEventInterstitial instead of GADCustomEventBanner (see the GADCustomEventInterstitial.h and GADCustomEventInterstitialDelegate.h files for details).

8. (optional) Check the value of adNetworkClassName

You can optionally check the adNetworkClassName property on DFPBannerView, which returns the ad network class name of the ad network that fetched the current banner once the adViewDidReceiveAd callback is called:

- (void)adViewDidReceiveAd:(DFPBannerView *)bannerView {
 NSLog(@"Banner adapter class name: %@", bannerView.adNetworkClassName);
}
Similarly, for interstitials, check the adNetworkClassName property on DFPInterstitial inside interstitialDidReceiveAd:
- (void)interstitialDidReceiveAd:(DFPInterstitial *)interstitial {
 NSLog(@"Interstitial adapter class name: %@", interstitial.adNetworkClassName);
}
For standard DFP ads and mediated Google AdMob ads, adNetworkClassName returns GADMAdapterGoogleAdMobAds. For ads fetched via custom events, it returns GADMAdapterCustomEvents.

Back to top

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.