Using a Custom Correlator with the Mobile Ads SDK

  • Some apps require correlating two ad requests, which is not allowed by default in the Google Mobile Ads SDK.

  • A correlator value is a random 16-digit unsigned integer string used to link ad requests.

  • By manually applying the same correlator to multiple ad requests, you can achieve correlation.

  • The correlator lifespan is 30 seconds, and requests need to be made sequentially within this timeframe for correlation to work.

  • It's best practice to limit sequential requests to 3-5 and generate a new correlator for each new long-lived page view.

Some apps require two ad requests to be correlated with each other.

The Google Mobile Ads SDK does not allow you to correlate two requests, which makes it difficult to prevent the same creative from serving to two similar ad requests. Correlated ad requests are also required for roadblocks and competitive exclusion features in Ad Manager.

A correlator value is a random unsigned integer, 16 characters in length, that is represented as a string. By default, the GMA SDK generates a new correlator with each ad request, meaning no two requests are correlated.

To correlate two requests, you can manually override the correlator generated by the GMA SDK, and apply the same correlator to multiple ad requests. To use this feature, you need to generate your own random correlator. Here are the examples of how to pass your own correlator:

Java

Bundle extras = new Bundle();
String correlator = "2510196024846425"; // make randomly - should be 16 digits.
extras.putString("correlator", correlator);
AdManagerAdRequest request = new AdManagerAdRequest.Builder()
    .addNetworkExtrasBundle(AdMobAdapter.class, extras)
    .build();

Kotlin

val extras = Bundle()
val correlator = "2510196024846425" // make randomly - should be 16 digits.
extras.putString("correlator", correlator)
val request = AdManagerAdRequest.Builder()
    .addNetworkExtrasBundle(AdMobAdapter::class.java, extras)
    .build()

The correlator lifespan is 30 seconds. Requests made more than 30 seconds apart will not be considered correlated by the server.

Best practices

Using the custom correlator will give Ad Manager the context it needs to prevent it from selecting the same creative, but the ad requests need to be made sequentially: make an ad request, get the response, then make the next request.

You can do this multiple times, but the more calls you make, the more resources you will consume. It's best to limit to 3 - 5 sequential requests. You can make additional calls as the user scrolls down the page.

Since the correlator expires after 30 seconds, you don't need to generate a new value for the same long page view. Generate a new correlator at the start of each new long-lived page view. If you no longer need this behavior, stop passing your own correlator.

In order to prevent the ads you returned from serving in subsequent calls after the correlator expires, consider adding in a frequency cap of 1 ad every 5 to 10 minutes. The time you select should coincide with typical usage of your app. Frequency caps can get expunged if you don't render the ads, so if you make an ad request, but don't render the ad and make additional calls, you might receive the same ad.