Mediation

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 iOS app and setting up additional request parameters.

Prerequisites

  • An iOS app with the Google Mobile Ads SDK integrated (If you don't have one, see Get Started.) See About AdMob Mediation for a walk-through of what mediation is and how to use the AdMob Mediation UI. Then, continue reading these instructions for adding mediation code to your app.

Add mediation adapters to your project

  1. Integrate ads into your app the same as before. To integrate non-interstitial ads (banner size, leaderboard size, and so on), see Banner Ads. To integrate interstitial ads (full-screen ads that mask all other content), see Interstitial Ads.

    The following steps change your ad placement into a mediation placement that can show ads from multiple networks.

  2. Download the adapters and SDKs for each ad network you'd like to serve ads from. You can find links to them on the mediation networks page.

  3. Add the downloaded network adapters/SDKs in Xcode: right-click on your project and click Add Files to project.

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

    There's no need to write additional code to create ad views from each ad network. Mediation invokes each ad network's adapter and SDK as necessary to create ads. Below, you can see how to set up mediation listeners that notify you of ad events for all of your networks.

Optional setup

Specify additional request parameters

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 your app already uses CoreLocation, you can use your existing CLLocationManager instance to set the precise location.

Here is an example:

Objective-C

GADRequest *request = [GADRequest request];
CLLocation *currentLocation = locationManager.location;
if (currentLocation) {
  [request setLocationWithLatitude:currentLocation.coordinate.latitude
                         longitude:currentLocation.coordinate.longitude
                          accuracy:currentLocation.horizontalAccuracy];
}

Swift

let request = GADRequest()
if let currentLocation = locationManager.location {
  request.setLocationWithLatitude(CGFloat(currentLocation.coordinate.latitude),
      longitude: CGFloat(currentLocation.coordinate.longitude),
      accuracy: CGFloat(currentLocation.horizontalAccuracy))
}

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

You can target on birthday and gender as well as location and you can set COPPA tags.

Demographic information

GADRequest provides methods for specifying demographic information like gender and birthday. These are passed along to all networks that accept them. Here is an example:

Objective-C

GADRequest *request = [GADRequest request];
request.gender = kGADGenderFemale;
NSDateComponents *components = [[NSDateComponents alloc] init];
components.month = 1;
components.day = 1;
components.year = 1985;
request.birthday = [[NSCalendar currentCalendar] dateFromComponents:components]

Swift

let request = GADRequest()
request.gender = .female
var components = DateComponents()
components.month = 1
components.day = 1
components.year = 1985
request.birthday = Calendar.current.date(from: components)

Network-specific parameters

Some networks also support other request parameters that are specific to their network. These are not required but can be used by networks to serve more finely targeted ads. Ad networks with extra parameters expose a class in their adapter that extends GADExtras.

Let's say there is a sample ad network that exposes an income parameter. That ad network may provide a class that looks like this:

Objective-C

@interface SampleExtras : GADExtras

  @property(nonatomic, assign) NSInteger income;

@end

Swift

class SampleExtras: GADExtras {
  var income = 0
  ...
}

If you're mediating this network, you can provide the income to that particular network by passing an instance of their extras class to registerAdNetworkExtras::

Objective-C

SampleExtras *sampleExtras = [[SampleExtras alloc] init];
sampleExtras.income = 65000;
[request registerAdNetworkExtras:sampleExtras];

Swift

let sampleExtras = SampleExtras()
sampleExtras.income = 65000
request.register(sampleExtras)

Request agent (for third-party libraries)

Third-party libraries that reference the Mobile Ads SDK should 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:

Objective-C

GADRequest *request = [GADRequest request];
request.requestAgent = @"Cool Ad Network"

Swift

let request = GADRequest()
request.requestAgent = "Cool Ad Network"

Set up event notification

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

Ad Events provides instructions on how to register for ad events.

Check the value of adNetworkClassName

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

Objective-C

- (void)adViewDidReceiveAd:(GADBannerView *)bannerView {
  NSLog(@"Banner adapter class name: %@", bannerView.adNetworkClassName);
}

Swift

func adViewDidReceiveAd(_ bannerView: GADBannerView) {
  print("Banner adapter class name: \(bannerView.adNetworkClassName)")
}

Similarly, for interstitials, check the adNetworkClassName property on GADInterstitial inside interstitialDidReceiveAd:

Objective-C

- (void)interstitialDidReceiveAd:(GADInterstitial *)interstitial {
  NSLog(@"Interstitial adapter class name: %@", interstitial.adNetworkClassName);
}

Swift

func interstitialDidReceiveAd(_ ad: GADInterstitial) {
  print("Interstitial adapter class name: \(ad.adNetworkClassName)")
}
For ads returned from AdMob, adNetworkClassName returns GADMAdapterGoogleAdMobAds. For ads fetched via custom events, it returns GADMAdapterCustomEvents.

Native Ads Advanced 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

Native ads advanced field descriptions 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 adLoader:didReceiveNativeAppInstallAd: delegate method that checks to see if the price asset is present in a GADNativeAppInstallAd object and shows or hides the corresponding asset view as appropriate:

if (nativeAppInstallAd.price) {
  ((UILabel *)appInstallAdView.priceView).text = nativeAppInstallAd.price;
  appInstallAdView.priceView.hidden = NO;
} else {
  appInstallAdView.priceView.hidden = YES;
}

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 an NSDictionary property called extraAssets.

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:

NSString *category = nativeAppInstallAd.extraAssets["CATEGORY_KEY"];

The names of the keys used to retrieve assets from the extraAssets property 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 subclasses of GADAdLoaderOptions (such as GADNativeAdImageAdLoaderOptions) 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 disableImageLoading 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 disableImageLoading.

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

Does GADBannerViewDelegate still work with mediation?
Yes, it still works with all mediation networks.
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 "<Google> Cannot find an ad network adapter with the name(s): (GADMSomeAdapter)" 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...

AdMob by Google
AdMob by Google