Use a Custom Correlator with Google Mobile Ads SDK

  • Some apps require correlating two ad requests, which is not allowed by default in the Google Mobile Ads SDK but is needed for features like roadblocks and competitive exclusion in Ad Manager.

  • A correlator is a 16-character random unsigned integer string, and by default, the GMA SDK generates a new one for each ad request.

  • You can correlate requests by manually generating a random correlator and applying it to multiple ad requests within a 30-second lifespan.

  • To use a custom correlator effectively, make ad requests sequentially and limit the number of sequential calls to 3-5 to avoid excessive resource consumption.

  • Generate a new correlator for each new long-lived page view, and consider using frequency caps if you need to prevent previously returned ads from serving after the correlator expires.

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:

Swift

var correlator = "2510196024846425" // make randomly - should be 16 digits.
let request = AdManagerRequest()
let extras = Extras()
extras.additionalParameters = ["correlator": correlator];
request.register(extras)

Objective-C

NSString *correlator = @"2510196024846425" // make randomly - should be 16 digits.
DRPRequest *request = [[GAMRequest alloc] init];
GADExtras *extras = [[GADExtras alloc] init];
extras.additionalParameters = @{ @"correlator": correlator};
[request registerExtras:extras];

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.