Mediation Test Suite

The Google Mobile Ads Mediation Test Suite lets you test whether you have correctly configured your app and ad units to be able to display ads from third-party networks through mediation. This guide outlines how to use the Google Mobile Ads Mediation Test Suite in your iOS app by integrating the tool into your app.

Prerequisites

  • Use Xcode 14.1 or higher.
  • Target iOS 11.0 or higher.
  • Create an Ad Manager account and register an app.
  • Ensure you have correctly entered your app ID in your Info.plist.

Installation

  1. Add the following line to your project's Podfile:

    pod 'GoogleMobileAdsMediationTestSuite'

  2. From the command line run:

    pod install --repo-update

Manual integration

  1. Download and unzip Mediation Test Suite.
  2. Add GoogleMobileAdsMediationTestSuite.xcframework to your project.
  3. In your target's Build Phases, add GoogleMobileAdsMediationTestSuite.bundle under Copy Bundle Resources.
  4. Download the latest release of Material Components for iOS and add it to your project. Mediation Test Suite requires the Cards, Dialogs, and Tabs components.

Update your Info.plist

Mediation Test Suite requires that you set your Ad Manager app ID in order to launch Mediation Test Suite for Ad Manager.

Launching the Mediation Test Suite

To display the tool, first import the framework:

Swift

import GoogleMobileAdsMediationTestSuite

Objective-C

@import GoogleMobileAdsMediationTestSuite;

Next, after your view has appeared, show the test suite as follows:

Swift


GoogleMobileAdsMediationTestSuite.presentForAdManager(on:self, delegate:nil)

Objective-C


[GoogleMobileAdsMediationTestSuite presentForAdManagerOnViewController:self delegate:nil];

This optional delegate notifies you when the Mediation Test Suite is dismissed. To implement the delegate callback, conform to the GMTSMediationTestSuiteDelegate protocol and implement the mediationTestSuiteWasDismissed method.

The tool opens with the following disclaimer:

Tick the checkbox and press Agree to proceed.

You're then presented with two tabs: Yield Groups and Bidding Partners.

Yield Groups represents all the Yield Groups configured for the app.

Bidding partners is a list of all Yield Partners configured for bidding that have their own SDK for ad rendering and have an associated ad unit mapping configured in your account.

If you don't see a list of yield groups, either the network call failed or no yield groups were found.

The list in each tab is separated into three sections:

  • Implementation Errors: Entries with an issue with the integration of the SDK or Adapter for one of the networks.
  • Configuration Errors: Generally these are untested and as such it is unknown whether the credentials configured for all networks are valid.
  • Working: All network entries have had a successful ad load.

Yield groups are listed by their ID. This ID is the same as the yield_group_id parameter in the URL when viewing the yield group in your Ad Manager UI.

For the URL:

https://admanager.google.com/6499#delivery/yield_group/detail/yield_group_id=140356`

the yield group ID is 140356.

After all of a yield group's networks are tested successfully, the yield group will move from the Configuration Errors section to the Working section.

To search the list of yield groups, press the search icon at the top and enter a yield group ID. You can also search by network name or by ad format.

For each yield group, this screen provides warnings if:

  • An ad source SDK is not installed

  • An ad source adapter is not installed

If testing is possible, the screen also shows overall test result status for all ad sources.

Select a yield group to move to the Yield Group Details screen.

Yield group details

This screen shows the details for the yield group, including the yield group ID, the ad format, and the mediation waterfall configured for the yield group:

Note the following aspects on this screen:

Ad source summary

For each ad source, there are indicators showing whether the SDK and adapter is installed and the result of the last test for this configuration in this session.

For custom events, a Custom Event: custom event label is used. The adapter status indicator for a custom event will be positive if the class you've specified for the custom event is found. You can load and view ads for custom events in the same way as other networks.

Search

Pressing the search icon presents a search screen where you can search for ad sources according to their name.

Batch testing

Each ad source can be selected to be tested in a batch by checking the checkbox to the left of the ad source name. A new option then appears in the navigation bar:

Press the Load Ads button in the top right to load ads for the selected ad sources in sequence. A progress indicator is displayed while testing takes place. Pressing the back icon in the top left clears the selection.

Loading and displaying ads

Tap on an ad source entry to see the ad source details screen:

The screen indicates, for the given ad source:

  • If the SDK is installed and, if available, the SDK version.
  • If the adapter is installed and, if available, the adapter version.
  • The adapter initialization status, if available.
  • The parameters for the configuration that were entered in the Ad Manager console.

After you've installed all required components, you can proceed to test loading an ad. Tap on Load Ad to send an ad request to the ad source's SDK. Once the ad request completes, an update saying whether the request succeeded or failed is presented.

If the request failed, check your console logs for messages from the SDK being tested.

If the request succeeded:

  • For banner ads, the ad is shown inline.
  • For interstitial or rewarded ads, you can show the ad by tapping on Show Ad.

  • For native ads, the assets returned are shown inline.

    The ad opens in a new screen, for example:

When you return to the Details screen, the results of the last time you tested the ad in the yield groups list screen are displayed. The successfully loaded ad sources are moved to the bottom of the list surfacing the ad sources needing further testing.

Bidding partners

See the Verify bidding setup guide for details on testing bidding.

Enabling testing in production

By default, the Mediation Test Suite will only launch in development, adhoc, and enterprise builds. This is meant to prevent end users from inadvertently launching the test suite.

If you need to run the Mediation Test Suite on a device once your app is in production, register your device as a test device with the SDK.

When including the Mediation Test Suite in a production app, you'll need a hidden way to launch the test suite (for example, a secret gesture or debug menu). You'll then be able to launch the test suite on any device that's been allowlisted in the build.

Configuring ad requests with network extras (optional)

Certain mediated networks, such as Liftoff Monetize, have the option to provide a custom network extras object to provide additional information to requests to their network.

If you need to provide network extras for your mediation requests, you can set an ad request for the test suite to use with the [GoogleAdsMediationTestSuite setAdRequest:] class method:

Swift

let request = GAMRequest()
...
// Set your network extras for your chosen networks here.
// I.e., for each network extras object, call
// 'request.register(\)'
...
GoogleAdsMediationTestSuite.setAdRequest(request);

Objective-C

GAMRequest request = [GAMRequest request];
...
// Set your network extras for your chosen networks here.
// I.e., for each network extras object, call
// '[request registerAdNetworkExtras:\];'
...
[GoogleAdsMediationTestSuite setAdRequest:request];

Ensure that you do this before launching the Mediation Test Suite.

This enables you to instantiate and configure an ad request with any required extras, which the test suite can then use in its request to the mediated network.

Advanced CocoaPods configuration (optional, debug only)

If you only want to include the pod in the debug version of your app, you can specify this in your Podfile as a pod for only the Debug build configuration. You need to also guard any code that calls the tool with #ifdef DEBUG statements or similar.

To include the pod only in the Debug configuration, use the following line:

pod 'GoogleMobileAdsMediationTestSuite', :configurations => ['Debug']

Make sure to wrap all references to the framework and its classes with #ifdef DEBUG:

Swift

import UIKit
#if DEBUG
import GoogleMobileAdsMediationTestSuite
#endif
import GoogleMobileAds

let APP_ID = "ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
    }

  @IBAction func presentMediationController(_ sender: AnyObject) {
      #if DEBUG
        GoogleMobileAdsMediationTestSuite.present(withAppId:APP_ID, on:self, delegate:nil)
      #endif
    }

Objective-C

#import "ViewController.h"
#ifdef DEBUG
@import GoogleMobileAdsMediationTestSuite;
#endif
#import <GoogleMobileAds/GoogleMobileAds.h>

static NSString *APP_ID = @"ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy";

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
}

- (IBAction)presentMediationController:(id)sender {
#ifdef DEBUG
    [GoogleMobileAdsMediationTestSuite presentWithAppId:APP_ID
                                       onViewController:self
                                               delegate:nil];
  }
#endif
}

Changelog

3.0.0

Release Date: 2022-05-02

  • Added support for Google Mobile Ads SDK 9.0.0 and higher.
  • Added ability to test Snap and Pangle bidding.
  • Updated minimum supported Xcode version to 13.2.1.

2.0.0

Release Date: 2021-07-27

  • Added support for Google Mobile Ads SDK 8.0.0 and higher.
  • Added ability to test AdColony banner bidding, maio bidding, and i-mobile waterfall configurations.
  • Updated MaterialComponents dependency version to 124.0.
  • Updated distribution to xcframework. Added arm64 simulator architecture, removed i386.
  • Requires Xcode 12 to build.

1.4.0

Release Date: 2020-12-01

  • Add support for Ad Manager with GoogleMobileAdsMediationTestSuite presentForAdManagerOnViewController:delegate API.
  • Add ability to register test devices for AdMob via the AdMob UI.
  • Updated MaterialComponents dependency version to 119.0.

1.3.0

Release Date: 2020-07-31

  • Minor design updates.
  • Updated MaterialComponents dependency version to 111.0.

1.2.1

Release Date: 2020-05-20

  • Added Fyber Marketplace support.
  • Updated MaterialComponents dependency version to 109.0.

1.2.0

Release Date: 2020-02-28

  • Added ability to load Open Bidding ads.
  • Updated MaterialComponents dependency version to 103.0.

1.1.1

Release Date: 2019-11-12

  • Fixed issue with loading rewarded ads on newer adapter versions.
  • Fixed presentation issue on iOS 13.
  • Updated MaterialComponents dependency version to 94.0.
  • Minimum required version is now iOS 9.0.

1.1.0

Release Date: 2019-09-18

  • Added initial open bidding support (ability to review configurations, cannot load ads).
  • Added support for Du Ad Platform and Verizon Media networks, as well as MoPub rewarded ads.
  • Added GoogleMobileAdsMediationTestSuite presentOnViewController:delegate: API which doesn't require app ID - uses AdMob app ID from Info.plist.
  • Deprecated GoogleMobileAdsMediationTestSuite presentWithAppID:onViewController:delegate: API.

1.0.0

Release Date: 2019-04-22

  • General release out of beta.

0.9.3

Release Date: 2019-02-22

  • Fixed bug where custom events would not load ads.

0.9.2

Release Date: 2019-02-07

  • Fixed issue with Mediation Test Suite loading ads from other networks when testing a network.
  • Add Native Assets view for Native Ads loading.
  • Add support for legacy 'Banner,Interstitial' ad units.
  • Add safeguards against launching the test suite in production. Mediation Test Suite will no longer launch in App Store builds, unless running on a device whose AdMob device ID is explicitly added to Test Devices.
  • Added localization of test suite for JA, KO, VI, ZH-CN.
  • Update Material Components dependency to 76.0.

0.9.1

Release Date: 2018-09-27

  • Update Material Components dependency to 63.0.

0.9.0

Release Date: 2018-08-07

  • Initial Version.