Open Bidding Adapter Development

This guide is intended for ad networks looking to build an open bidding adapter in order to participate in real-time bidding (RTB) within Google mediation. If you are a publisher, see the publisher mediation instructions.

An open bidding adapter is the client-side part of the integration. The adapter enables your ad network SDK to communicate with the Google Mobile Ads SDK to load ads served by your bidder.

For Open Bidding to work correctly your adapter will need to handle initialization, collecting signals, loading ads, and relaying ad lifecycle events. In this guide we will walk you through how your adapter should be implemented to handle these operations.

Note: Participation in open bidding also requires a bidder that can respond OpenRTB requests. Instructions on how to stand up a bidder are outside the scope of this guide.

Workflow of an open bidding adapter

Initialization

A detailed flow of the entire request-response-rendering lifecycle of an adapter is shown below:

The adapter is responsible for the following portions of the workflow:

• Steps 4-7: Initialize your adapter and call back the Google Mobile Ads SDK once initialization completes.

• Steps 10-13: Collect signals from your ad network SDK to be sent to your bidder to participate in an RTB request, and forward them to the Google Mobile Ads SDK.

• Steps 18-21: Should your bidder return the winning bid, load the ad according to the response from your bidder. Once loaded, notify the Google Mobile Ads SDK that the ad was loaded.

• Step 23 and later: While your ad is displaying, notify the Google Mobile Ads SDK of impression and click events, as well as the other ad events that occur during the presentation lifecycle of your ad.

Note: The Google Mobile Ads SDK separately tracks impression events, but it is also important that you forward your ad network's impression event so that we can check for discrepancies.

Implementing the open bidding adapter

To create an open bidding adapter for the Google Mobile Ads SDK, you must extend the RtbAdapter abstract class. The following sections explain each abstract method in RtbAdapter.

getSDKVersionInfo()

Here you should return your SDK's version. This version is passed to your bidder as part of the OpenRTB request.

This method requires you to return a VersionInfo. The example below shows how you might convert your SDK's string version into a VersionInfo.

@Override
public VersionInfo getSDKVersionInfo() {
  // Get your SDK's version as a string. E.g. "1.2.3"
  // String versionString = YourSdk.getVersion();
  String splits[] = versionString.split("\\.");
  if (splits.length >= 3) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]);
      return new VersionInfo(major, minor, micro);
   }

   String logMessage = String.format("Unexpected SDK version format: %s." +
           "Returning 0.0.0 for SDK version.", sdkVersion);
   Log.w(TAG, logMessage);
   return new VersionInfo(0, 0, 0);
}

getVersionInfo()

Here you should return your adapter's version. This version is passed to your bidder as part of the OpenRTB request.

Google's open source and versioned adapters use a 4-digit adapter version scheme, but the VersionInfo only allows for 3 digits. To work around this, it is recommended to combine the last two digits into the patch version, as shown below.

@Override
public VersionInfo getVersionInfo() {
  // Get your adapters's version as a string. E.g. "1.2.3.0"
  String versionString = BuildConfig.VERSION_NAME;
  String splits[] = versionString.split("\\.");
  if (splits.length >= 4) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]) * 100 + Integer.parseInt(splits[3]);
      return new VersionInfo(major, minor, micro);
    }

    String logMessage = String.format("Unexpected adapter version format: %s." +
                "Returning 0.0.0 for adapter version.", versionString);
    Log.w(TAG, logMessage);
    return new VersionInfo(0, 0, 0);
}

initialize()

Timeout: 30 seconds

The initialize() method is the first method called in your adapter. It is called only once per session. This method provides you with a list of MediationConfiguration objects that represent the full list of placements in this app that are configured for your ad network; You can loop through this list to parse the credentials for each placement, and pass relevant data to your SDK for initialization.

Once your SDK is initialized and is ready to receive ad requests, invoke the onInitializationSucceeded() method of the InitializationCompleteCallback. This callback is forwarded to the app publishers so that they can know they can start loading ads.

Note: The initialize() method is called on a throwaway instance of an adapter. No other methods will be called on this particular instance. If your adapter needs to save state as a result of this method, any state should be static.

@Override
public void initialize(Context context,
    InitializationCompleteCallback initializationCompleteCallback,
    List<MediationConfiguration> mediationConfigurations) {
  // Initialize your ad network's SDK.
  ...

  // Invoke the InitializationCompleteCallback once initialization completes.
  initializationCompleteCallback.onInitializationSucceeded();
}

collectSignals()

Timeout: 1 second

Each time the publisher requests an ad, a new instance of your RtbAdapter is created and the collectSignals() method is called. This instance of RtbAdapter will be used for the duration of the ad request, response, and rendering lifecycle for that ad. The collectSignals() method enables your adapter to provide signals from the device to be sent to your bidder in an OpenRTB request.

collectSignals() is called on a background thread. The Google Mobile Ads SDK simultaneously asks for signals from all adapters participating in open bidding mediation. Please be respectful and limit calls to the UI thread during this time. Any heavy work that your adapter or SDK needs to do to collect signals should be done in the initialize() method and cached.

Once you have your signals ready, call the onSuccess() callback with your encoded signals.

Here's an example implementation:

@Override
public void collectSignals(RtbSignalData rtbSignalData,
                           SignalCallbacks signalCallbacks) {
  String signals = YourSdk.getSignals();
  signalCallbacks.onSuccess(signals);
}

If your adapter fails to collect signals, call signalCallbacks.onFailure() with a string explaining the error that occurred.

Note: The signals string could represent any object, and it could be in any format, such as plain JSON, Base64 encoded, or any other form of encryption you choose. Encrypting signals is recommended to ensure that signals are opaque outside of your network.

Implement ad loading methods

Timeout: 10 seconds

If your bidder returns the winning bid, the Google Mobile Ads SDK calls your adapter to load the winning ad, passing you any data that your bidder returned that your SDK needs to load that ad.

The exact load method that is called depends on the ad format this request is for:

Ad Format	Load method
Banner	loadBannerAd()
Interstitial	loadInterstitialAd()
Rewarded	loadRewardedAd()

Implement these methods for the ad formats your adapter supports.

The load method is called on the UI thread, on the same instance of the adapter from which you provided signals. This method provides you the following parameters:

• A MediationAdConfiguration, which contains parameters your SDK needs to load the ad for the winning bid, such as the bid response and any credentials the publisher configured in the AdMob UI.

• A MediationAdLoadCallback object used to notify the Google Mobile Ads SDK when the loading succeeds or fails.

Once your SDK loads the ad, call mediationAdLoadCallback.onSuccess(). In the event ad loading fails, call mediationAdLoadCallback.onFailure() with a string explaining the error that occurred.

The mediationAdLoadCallback.onSuccess() method requires that you pass in an object that confirms to one of the "Ad" interfaces defined by the Google Mobile Ads SDK. These ad interfaces ask you to provide some information about the ad.

MediationAdConfiguration also has a getWatermark() method to return a base64-encoded string representing a PNG image. This image should be tiled in a transparent overlay on your ads. Reach out to Google for additional guidance on how to render the watermark. It contains metadata about the ad being shown for use by publishers to determine the source of ads shown.

For banners, you'll be asked to provide the banner view. For interstitial and rewarded ads, you'll be asked to implement a show() method to show the ad at a later point in time. As a best practice, we recommend making your class that does the ad loading also be responsible for implementing these ad methods.

The following is a sample implementation of loadBannerAd(). Keep in mind that your adapter's implementation will look different, as your adapter integrates against a different SDK.

public final class SampleRtbAdapter extends RtbAdapter {
  ...

  @Override
  public void loadBannerAd(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> callback) {

      SampleBannerRenderer bannerRenderer =
          new SampleBannerRenderer(adConfiguration, callback);
      bannerRenderer.render();
    }
}

// Renders a banner ad, and forwards callbacks to the Google Mobile Ads SDK.
public class SampleBannerRenderer implements MediationBannerAd {
  private MediationBannerAdConfiguration adConfiguration;
  private final MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback;
  private AdView adView;
  private MediationBannerAdCallback callback;

  public SampleRtbBannerRenderer(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback) {
    this.adConfiguration = adConfiguration;
    this.adLoadCallback = adLoadCallback;
  }

  public void render() {
    adView = new AdView(adConfiguration.getContext());
    adView.setAdSize(adConfiguration.getAdSize());
    // serverParameters are the parameters entered in the AdMob UI for your network.
    adView.setAdUnitId(adConfiguration.getServerParameters().getString("adUnitId"));

    // Map the callbacks from your SDK to Google's SDK.
    adView.setAdListener(new AdListener() {
      // See the next step for more information on callback mapping.
      // ...
    });

    // Get the bid response and watermark from the ad configuration and
    // pass the relevant information to your SDK.
    String ad = adConfiguration.getBidResponse();
    String watermark = adConfiguration.getWatermark();
    Bundle extras = new Bundle();
    extras.putString("bid", ad);
    extras.putString("watermark", watermark);
    AdRequest request = new AdRequest.Builder()
        .addNetworkExtrasBundle(AdMobAdapter.class, extras)
        .build();
    adView.loadAd(request);
  }

  // MediationBannerAd implementation

  @NonNull
  @Override
  public View getView() {
    return adView;
  }
}

Relay ad presentation lifecycle events

The final responsibility of the adapter is to notify the Google Mobile Ads SDK of any presentation lifecycle events, so that they can be forwarded to the publisher. The publisher expects these callbacks at specific times no matter which ad network serves the ad, so it's important that as many of these callbacks are invoked as possible, and at the right time, so that the Google Mobile Ads SDK can forward them to the publisher.

Adapters should invoke the following events when applicable:

Common to all formats
Method	When to call
reportAdClicked()	The ad was clicked.
reportAdImpression()	The ad rendered an impression.
onAdOpened()	The ad presented a full screen view.
onAdClosed()	The ad's full screen view has been closed.
onAdLeftApplication()	The ad caused the user to leave the application.
Rewarded ads
onRewarded()	The user is granted a reward.
Video callbacks (rewarded and native ads)
onVideoStarted()	The ad's video started.
onVideoCompleted()	The ad's video completed.

The adapter gets a MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> object back upon calling mediationAdLoadCallback.onSuccess(). Adapters are expected to hold onto this object and use it to invoke presentation events that occur on your ad.

Typically, most of these events are driven by your ad network's SDK. The adapter's role is simply to map the callbacks from your ad network SDK to the Google Mobile Ads SDK.

The following example demonstrates how you would forward callbacks from your SDK's ad listener to the Google Mobile Ads SDK:

adView.setAdListener(new AdListener() {
    public void onAdLoaded() {
        callback = adLoadCallback.onSuccess(SampleBannerRenderer.this);
    }

    public void onAdImpression() {
        if (callback != null) {
            callback.reportAdImpression();
        }
    }

    public void onAdFailedToLoad(LoadAdError adError) {
        adLoadCallback.onFailure("Error: " + adError.toString());
    }

    public void onAdClosed() {
        if (callback != null) {
            callback.onAdClosed();
        }
    }

    public void onAdOpened() {
        if (callback != null) {
            callback.onAdOpened();
            callback.reportAdClicked();
        }
    }

    public void onAdLeftApplication() {
        if (callback != null) {
            callback.onAdLeftApplication();
        }
    }
});

Sample app

The following sample app demonstrates the complete implementation of an adapter.

Download Sample

When using this sample with the Android emulator, if you keep seeing a Google ad returned and the Sample adapter is never asked to render an ad, you can try using Charles Proxy and enable the Rewrite feature. Import the following rewrite rule to update certain parameters in the ad response for requests to googleads.g.doubleclick.net/mads/gma.

Download rewrite rule

For physical devices this rule is not necessary.