Mediation Test Suite

Caution: Mediation Test Suite is in maintenance mode. We recommend using ad inspector as your on-device debugging tool.

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 Android app by integrating the tool into your app.

Prerequisites

• Android minimum API level 19 or higher.
• Google Play services 9.8.0 or higher.

• Create an AdMob account and register an app.

• Ensure you have correctly entered your app ID in your AndroidManifest.xml.

Installation

Using Gradle

Copy the following required dependencies into your apps build.gradle file:

dependencies {
    // You should already have the ads dependency in your app.
    implementation 'com.google.android.gms:play-services-ads:22.1.0'
    implementation 'com.google.android.ads:mediation-test-suite:3.0.0'
}

Include the google() repository in your top-level build.gradle file:

// Top-level build file where you can add configuration options common to all
// sub-projects/modules.

buildscript {

   repositories {
       google()
   }
   dependencies {
       classpath 'com.android.tools.build:gradle:3.2.1'

       // NOTE: Do not place your application dependencies here; they belong
       // in the individual module build.gradle files
   }
}

allprojects {
   repositories {
       google()
   }
}

Launching the Mediation Test Suite

Use the following line of code to launch the Mediation Test Suite:

MediationTestSuite.launch(MainActivity.this);

Key Point: Note that this requires that you have correctly entered your app ID in your AndroidManifest.xml.

Navigating the Test Suite

The tool opens with the following disclaimer:

Key Point: The disclaimer shows every time the test suite launches as a reminder that you should turn on test mode for your mediation ad sources.

Tick the checkbox and press Agree to proceed.

You're then presented with a list of ad units for your account, separated into two tabs: Failing Ad Units and Working Ad Units.

Registering a test device

If your device is not already registered in the AdMob UI as a test device, you will see a prompt asking if you want to register your device as a test device:

Registering the device as a test device changes the following behavior in the Mediation Test Suite:

• Enables you to see ad unit names instead of ad unit IDs in the Test Suite UI.
• Enables you to search by ad unit name in addition to ad unit ID in the ad unit details screen.
• Enables your device to receive test ads from AdMob.

Key Point: Third-party ad networks may still serve live ads even if your device is in test mode. Check each third-party ad network’s testing instructions to ensure you have test ads enabled.

Clicking Register Device takes you to the Register test device page in the AdMob UI, with the device platform and device ID prefilled from the Mediation Test Suite. Add a name for your test device and click Save and your device will be registered. See Set up a test device for further guidance.

The device registration becomes active in the Mediation Test Suite usually within 15 minutes but can take up to 24 hours. In order to see the changes, close and reopen the Mediation Test Suite.

You need to be signed in to your AdMob account to access the Register test device page. If you don't have account access but still wish to add the device using this method, click the link and then, from the browser that opens, share the URL with an account owner. They can then follow the link and register your device in the account on your behalf.

If you don't wish to register as a test device at this time, press Dismiss.

Failing ad units

The Failing Ad Units list is separated into Missing Components and Configuration Errors:

After all of an ad unit's networks are tested successfully, the ad unit will move from the Failing tab to the Working tab. If you don't see a list of ad units, either the network call failed or no ad units were found.

If you want to search the list of ad units, press the search icon at the top and enter a string of an ad unit ID. You can also search by network name or by ad format.

For each ad unit, this screen provides warnings if:

• An ad source SDK is not installed

• An ad source adapter is not installed

• An ad source requires manifest entries that are not configured

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

Select an ad unit to move to the Ad Unit Details screen.

Ad unit details

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

Key Point: The test suite works for all open source and versioned adapters as well as custom event adapters. The ad networks in our open source initiative are listed on our mediation page.

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, any required manifest entries are found, 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:

Important: Ensure that you have test ads enabled for your device for the SDK that you are testing. Do this before testing any network ads configuration.

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.
• If any required manifest entries are properly configured.
• The adapter initialization status, if available.
• The parameters for the configuration that were entered in the AdMob 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 ad units list screen are displayed. The successfully loaded ad sources are moved to the bottom of the list surfacing the ad sources needing further testing.

Key Point: Test results are only stored in memory for a given app session and are not persisted between sessions. They are not stored on the device.

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 debuggable 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 bundle 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 MediationTestSuite.setAdRequest() static method:

Java

AdRequest requestBuilder = new AdRequest.Builder();
...
// Set your network extras for your chosen networks here.
// I.e., for each network extras bundle, call
// 'requestBuilder.addNetworkExtrasBundle(\,
// \)'
...
MediationTestSuite.setAdRequest(requestBuilder.build());

Kotlin

val requestBuilder = AdRequest.Builder()
...
// Set your network extras for your chosen networks here.
// I.e., for each network extras bundle, call
// 'requestBuilder.addNetworkExtrasBundle(\,
// \)'
...
MediationTestSuite.setAdRequest(requestBuilder.build())

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.

Changelog

v3.0.0

Release Date: 2022-06-14

• Updated play-services-ads dependency to 21.0.0.
• Updated flexbox dependency to use a version from Google's maven repository.
• Added support for Snap and Pangle bidding.
• Renamed "Facebook" to "Meta Audience Network".
• Updated the minimum API Level to API 19, and target API Level to API 31.

v2.0.0

Release Date: 2021-06-04

• Added compatibility with play-services-ads v20. Requires SDK version 20.0.0 or higher.
• Updated play-services-ads dependency to 20.1.0.
• Removed MediationTestSuite.addTestDevice() and MediationTestSuite.getTestDevices() APIs. Use MobileAds.setRequestConfiguration() to set test device identifiers instead.
• Added support for AdColony, Vungle, and IronSource banner configurations.
• Fixed bugs where i-mobile and Tapjoy incorrectly reported configuration errors.

v1.5.0

Release Date: 2020-11-23

• Added MediationTestSuite.launchForAdManager(Context context) API to enable Ad Manager support using combined app ID.
• Add support for registering test devices for AdMob.
• Fix issue where no configured ad unit mappings for Ad Manager would result in a crash.
• Remove obsolete manifest checks for Vungle SDK.
• Updated play-services-ads dependency to 19.5.0.

v1.4.0

Release Date: 2020-07-30

• Updated play-services-ads dependency to 19.3.0.
• Fix issue with banner,interstitial format causing crashes.
• Add support for Fyber Marketplace.
• Add support for banners for Chartboost.
• Fix issue with MoPub manifest entries detection.

v1.3.0

Release Date: 2020-02-27

• Add support for loading open bidding ads.
• Fix AppLovin and InMobi manifest requirements.

v1.2.2

Release Date: 2019-12-10

• Fix error in proguard file causing build errors in Unity.

v1.2.1

Release Date: 2019-11-11

• Updated ads dependency to 18.3.0.

v1.2.0

Release Date: 2019-09-11

• Updated for initial Open Bidding Support (ability to check configurations, not able to load ads).
• Added network support for i-mobile, Verizon Media.

v1.1.1

Release Date: 2019-06-28

• Update FlexboxLayout dependency for AndroidX support

v1.1.0

Release Date: 2019-06-27

• Update for AndroidX support
• Update adapters and networks and associated configurations (eg required manifest entries).
• Added MediationTestSuite.launch(Context) API that uses AdMob ID in AndroidManifest.xml.

v1.0.0

Release Date: 2019-04-22

• Version bump for general release.

v0.9.5

Release Date: 2019-02-22

• Fixed issue with providing JSON in a configuration parameter for an ad network / custom event.

v0.9.4

Release Date: 2019-02-11

• Updated dependencies including update Google Mobile Ads SDK to version 17.1.3.
• Fixed bug related to incorrect manifest permissions for AdColony SDK.
• Fixed issue with ad load context not being activity in API 28.

v0.9.3

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. It will no longer launch in release builds, unless running on a device whose AdMob device ID is whitelisted using MediationTestSuite.addTestDevice(String deviceHash).
• Added localization of test suite for JA, KO, VI, ZH-CN.

v0.9.2

Release Date: 2018-10-03

• Fixed issue with Facebook Interstitial having extra 'Account ID' parameter
• Fixed issue with incorrect permissions for Vungle SDK v5.x.
• Fixed bugs occurring in Android versions lower than v21.
• Fixed loading issue for ads when mediation adapter requires an activity context.

v0.9.1

Release Date: 2018-09-20

• Updated to support Vungle SDK version 6.x.
• Fixed issue where building with proguard would result in a crash.
• Added Java 7 support.

v0.9.0

Release Date: 2018-08-07

• Open Beta release with updated UI.
• Added batch testing ability.

v0.2

Release Date: 2018-03-20

• Updated to support publishers using Mediation Groups with the new AdMob UI.
• Updated UI.
• Added support for the following ad networks: Nend, myTarget, maio, and IronSource.

v0.1.1

Release Date: 2017-12-11

• Fixed a bug causing occasional NPEs when loading app configuration.

v0.1

Release Date: 2017-11-10

• Initial release. It launches, downloads mediation configurations, checks for adapter, SDK, and manifest correctness, and loads and shows ads from third party networks via their AdMob mediation adapters.