Ad inspector

Ad inspector is an in-app overlay that enables authorized devices to perform real-time analysis of test ad requests directly within a mobile app. It can be enabled with no coding required.

Using ad inspector, you can:

  • Inspect your ad units
  • Check whether your ads are filling as expected
  • Identify errors and view details about how to resolve them
  • View the details for each bidding ad network per request
  • View the mediation details for each ad network per request
  • Test individual third-party bidding or waterfall mediation ad sources
  • Verify that you've correctly configured each ad unit for bidding and waterfall mediation

This guide demonstrates how to launch and use the different features in ad inspector.

Prerequisites

In order to use ad inspector, you need to:

  • Use Mobile Ads Flutter plugin version 1.3.0 or higher.

Launch ad inspector

Ad inspector can be launched from anywhere in your app in the following ways:

  1. Use the launch button from the debug menu.
  2. Use the gesture that you selected in the ad inspector settings.
  3. Programmatically using the provided API.

Launch using debug menu

No changes are needed to your app to launch ad inspector through the debug menu; just find an ad served by your Ad Manager network, and touch and hold the ad with two fingers to open the debug menu. Then, select Open ad inspector.

If you didn't link your device, you may be asked to sign in to your Ad Manager account.

You can also select Ad inspector settings from the debug settings and choose a gesture that can open ad inspector in the future without having to go through the debug menu.

Launch programmatically

Ad inspector can also be launched programmatically:

MobileAds.instance.openAdInspector(
  (AdInspectorError? error) {
    // Error will be non-null if ad inspector closed due to an error.
  });

This API works for test devices registered programmatically.

View and troubleshoot ad units

Once launched, the main ad inspector screen appears, containing a list of all ad units the device has made ad requests for since ad inspector was enabled during this app session. The list also contains ad units with bidding enabled, ordered chronologically with the most recenly completed requests first, and those with no completed ad requests (dimmed):

We recommend initializing the Google Mobile Ads SDK before using ad inspector.

View mediation waterfall details for an ad unit

Tap an ad unit to view its SDK request log, which gives details about the mediation waterfall up to the point when the ad was filled (or the waterfall ended without a fill) for the latest ad requests.

Each request can be expanded using the disclosure indicator to show the results of the mediation waterfall for that request, along with any error and latency that was applicable for that request.

For third-party ad sources, the error messages are sent directly from the ad source. If you need more information, consult your third-party ad source.

View bidding details for an ad unit

If you are new to bidding, read the introduction to Open Bidding.

In the SDK request log, you can see the bidding ad sources that are called in the ad request. Tap an ad unit in the SDK request log to view the details of each ad source in the bidding auction.

The bidding results are sorted in order to bring the actionable items closer to the top of the list:

  • At the top is the ad network that won the auction.

  • Next are the ad networks with issues. You can follow the troubleshooting steps for the issues at the end of the bidding FAQs.

  • Then, there are the ad networks that had no ads returned or did not bid. This is a possible indicator of many different issues with the ad source as it might not have bid due to its setup or decisioning. You can refer to the ad source's setup guide or Open Bidding FAQs for more support.

  • Finally, at the bottom of the list are the ad networks that lost the bidding auction.

Mediation waterfall can place the ad source that won the bidding auction according to their eCPM value.

A mediation waterfall is the result of multiple yield groups competing for the same inventory. You can add up to ten third-party yield partners to a single yield group, including both bidding yield partners and mediation for mobile apps yield partners.

Advanced ad unit debugging

When troubleshooting ad units, it can be helpful to dig into the ad request and response to identify where something is failing, or to share with Google Support to aid in debugging. Tap the menu icon at the top of the waterfall chain and select Share ad request and response to export the full ad request and response. This saves you the trouble of having to run network traces on your own app.

Additionally, you can view decoded third-party bidding parameters by tapping the Third-party bidding parameter option on the same menu as the request string. This provides details about which third-party bidding parameters might be having issues, helping you to debug your app or validate that a network is collecting its signals successfully.

Android
iOS

View available adapters

Click the Adapters tab to see a list of all third-party adapters associated with the ad sources in the bidding or mediation configurations in your app. Then, expand cards to view their initialization statuses and SDK versions. Along with supported third-party adapters, you can also view custom event adapters. Custom events let publishers use ad networks that Ad Manager doesn't support. Custom events are distinguishable from standard third-party adapters in the adapter list by their unique class names. In addition to providing class name and status information, ad inspector also displays the labels assigned to those custom events in the Ad Manager web interface.

In the event the adapter isn't found or fails to initialize, see Inspect mobile app ad delivery for more information.

Android
iOS

Test your ad units

If you'd like to test your ad unit without having to navigate to it in your app's UI, ad inspector supports this directly from the ad unit detail screen. Additionally, you're able to test multiple ad units at once, asynchronously load and view your test ad requests, and even perform single ad source tests.

Ad testing

The ad inspector ad tests outlined in this section are a great tool for verifying your base ad experience and for validating your mediation configuration when used with single ad source testing.

When you're ready to test your ad unit, tap the Request test ad button at the top of your ad inspector screen to trigger your ad inspector ad test. Test results then appear in the SDK request log underneath the header Requested from ad inspector.

Learn how to use ad inspector in your app

Single ad source testing

Ad inspector has a feature to restrict ad requests in your app to only serve ads from a single bidding or waterfall mediation ad source. This lets you verify that you've correctly implemented the third-party adapter and that the ad source is serving as expected.

To enable this feature, toggle the Single ad source test switch at the bottom of the screen. This displays the following ad source selection dialog:

You must initialize the Google Mobile Ads SDK before you can use single ad source testing.

You can then select a single ad source to test. Once an ad source is selected, the following screen appears:

The single ad source test setting applies to any future ad requests you make in the same session. However, it doesn't apply to any previously cached ads in that session that have not yet been shown. Force restarting your app is recommended when applying a single ad source test in order to invalidate any cached ads that could be served instead of your chosen ad source receiving a request.

After restarting your app, all ad unit placements attempt to show an ad from the selected network only. Launching ad inspector when a single ad source test is active shows the active test ad source:

In single ad source test mode, all ad requests attempt to fill with the selected ad source, regardless of whether that ad source was configured for bidding or mediation for the requested ad unit. If the ad source you're testing is not in the mediation waterfall for an ad unit, you get a "No fill" error message.

In a single ad source test, you can tap an ad unit to view its SDK request log. This lets you know whether the ad source filled the ad requests made after single ad source testing is enabled. If the ad source failed to load an ad, an error message appears describing the error.

If you've added multiple instances of the selected ad source to a mediation waterfall, you would see each instance of the call to the ad source in the waterfall until the ad is either filled or the waterfall ended without a fill.

Stop a single ad source test

To stop the test, toggle off the switch:

A confirmation message then appears over the following restart screen:

We recommend a force restart of your app after stopping the test in order to invalidate any cached ads for the ad source that was tested.

Copy entire debugging outputs

The ad inspector supports copying a JSON string containing entire debugging outputs from the tool, including details of your Ad Manager app, adapter initialization statuses, and the testing results of all ad units.

To do so, tap the app icon seven times until you see the message Copied ad inspector JSON to clipboard.