Configure the ad transparency URL

The ad transparency URL lets you customize the AdChoices icon that shows in certain ads. By default, this icon appears to your users through a Google-rendered Ad Transparency and Control (AT&C) experience that includes information, such as the advertiser and the ad itself.

You can obtain the ad transparency URL by making an ad request to the Google Mobile Ads SDK, and receive a response with the ad transparency URL. After you receive the URL within your app, you can integrate a personalized icon that can comply with the design of your ads and present your own AT&C experience to your users.

This page covers how to request, parse, and validate the ad transparency URL.

Prerequisites

Before you continue, ensure you complete the following:

  • Set up native ads in your app. For details on native ads, see Native ads.
  • Request allowlist access to this feature. To request access, contact your account manager.
    • If you don't have access, your responses don't return the ad transparency URL, and the default icon renders as intended.

Request the URL

For GMA Next-Gen SDK to return you the ad transparency URL, you add an additional request parameter in your native ad requests. This parameter signals that your app is ready and prepared to handle a personalized icon.

In your request, you must add the key "ad_transparency_url_requested" with the value "1" to your network extras bundle. For details on network extras, see setGoogleExtrasBundle .

The following example sets this key and value to request the ad transparency URL:

Java 

private void loadNativeAd() {
  // Create an extra parameter that signals your AT&C implementation.
  Bundle extras = new Bundle();
  extras.putString("ad_transparency_url_requested", "1");
  NativeAdRequest adRequest = new NativeAdRequest.Builder("AD_UNIT_ID", List.of(NativeAdType.NATIVE))
      .setGoogleExtrasBundle(extras)
      .build();
}

Kotlin 

private fun loadNativeAd() {
  // Create an extra parameter that signals your AT&C implementation
  val extras = Bundle()
  extras.putString("ad_transparency_url_requested", "1");
  val adRequest = NativeAdRequest.Builder("AD_UNIT_ID", listOf(NativeAd.NativeAdType.NATIVE))
    .setGoogleExtrasBundle(extras)
    .build()
}

Replace AD_UNIT_ID with your ad unit ID. For example, ca-app-pub-3940256099942544/2247696110, for native ads.

Parse the URL

After you request the URL, you receive an ad response with the ad transparency URL in the response info object. For details on the response info object, see Response info.

You can access the ad transparency URL within the "ad_transparency_url" key from the response extras. The following example gets the ad transparency URL in the response info object:

Java 

nativeAd.getResponseInfo().getResponseExtras().getString("ad_transparency_url");

Kotlin 

nativeAd.getResponseInfo().responseExtras.getString("ad_transparency_url")

Validate the URL

To test and validate the ad transparency URL, verify that you don't see the Google-provided default icon in your native ad, but your personalized icon. Click the icon to view the AT&C experience.

Additionally, verify that you see the ad transparency URL from the response extras in your response info object. If you don't see the ad transparency URL, the default Google icon renders in place of your personalized icon. The following is an example ad transparency URL:

https://adssettings.google.com/whythisad?source=display&reasons=REASON_ID