AdChoices icon and overlay

Important: PAL iOS apps must set NonceRequest:iconsSupported to YES to receive the AdChoices icon and overlay in Google ad requests.

All apps that display personalized ads hosted by Google must implement the AdChoices icon and overlay, when provided by Google. AdChoices (also referred to as "Why this Ad?") is a transparency feature that explains to users why they are being shown a particular ad and provides information about how their privacy is protected.

For more information, see Why you're seeing an ad.

This guide explains how to extract the necessary information to properly implement AdChoices from your ad's VAST XML response or your DAI stream's metadata response.

Note: If your app uses the Interactive Media Ads SDK to render video ads, AdChoices support is automatically enabled and doesn't require any special parsing or rendering on your part. This guide only applies to publishers who are implementing video ads without the support of the IMA SDK.

Requirements for AdChoices rendering

To comply with Google's requirements for rendering AdChoices icons, your app or website must meet the following standards:

1. The AdChoices icon must be displayed overlaying any ad for which it is provided
2. The AdChoices icon must be displayed at the position indicated by the "X location" and "Y location" properties included in the icon data, and at the size defined by the width and height properties, in Density-independent Pixels (DP).
3. The AdChoices icon must not be obscured by other ad overlays or interface elements.
4. On platforms with click support or equivalent (e.g. touch or remote select), the AdChoices icon must be clickable.
5. On platforms with browser support, clicking the AdChoices icon must open a browser tab or window with the URL specified in the "ClickThrough" or "click_data" property.
6. On platforms without browser support, clicking the AdChoices icon must open a modal overlay, displaying one of the images specified in the "IconClickFallbackImage" or "click_fallback_images" property.
7. On platforms without browser support, the fallback image must be displayed at the size specified within the "IconClickFallbackImage" or "click_fallback_images" property, in Density-independent Pixels (DP).

Parse AdChoices from a VAST XML response

When working with an XML ad response, AdChoices is supported only in VAST version 3.0 and later. AdChoices is implemented as a VAST Icon.

VAST 4.2

If your XML ad response follows the VAST 4.2 standard, AdChoices is delivered as a VAST Icon. If your app or website fully supports VAST 4.2 Icons (section 3.11 of the VAST 4.2 standard), AdChoices support requires no further work.

If your app doesn't support VAST 4.2 icons, you need to manually parse icons with the program name "GoogleWhyThisAd" from your VAST response, based on that standard. You can use this sample VAST 4.2 xml for additional testing in your app.

Sample VAST 4.2 response

<?xml version="1.0" encoding="UTF-8"?>
<VAST version="4.2">
  <Ad id="20011">
    <Wrapper>
      ...
      <Creatives>
        ...
        <Creative id="5480" sequence="1">
          ...
          <Linear>
            ...
            <Icons>
              ...
              <Icon program="GoogleWhyThisAd" width="40" height="30" xPosition="left" yPosition="100" duration="00:00:10" offset="00:00:00" apiFramework="VAST" altText="AdChoices icon">
                <StaticResource creativeType="image/png">
                  <![CDATA[ https://storage.googleapis.com/interactive-media-ads/hosted-samples/wta/icon_adchoices.png ]]>
                </StaticResource>
                <IconClicks>
                  <IconClickThrough>
                    <![CDATA[ https://g.co/adsettings ]]>
                  </IconClickThrough>
                  <IconClickFallbackImages>
                    <IconClickFallbackImage width="950" height="600">
                      <AltText>
                        <![CDATA[ This ad was shown to you based on: * Google's estimation of your interests, based on your activity on Google on this device (for example, your searches) * the information on the website you were viewing. ]]>
                      </AltText>
                      <StaticResource creativeType="image/png">
                        <![CDATA[ https://storage.googleapis.com/interactive-media-ads/hosted-samples/wta/icon_adchoices_fallback_image.png ]]>
                      </StaticResource>
                    </IconClickFallbackImage>
                    ...
                  </IconClickFallbackImages>
                </IconClicks>
              </Icon>
              ...
            </Icons>
            ...
          </Linear>
          ...
        </Creative>
        ...
      </Creatives>
      ...
    </Wrapper>
    ...
  </Ad>
</VAST>

VAST 3.0

If your XML ad response follows the VAST 3.0 standard, AdChoices is delivered as a combination of a VAST Icon and a custom VAST extension. If your app or website fully supports the VAST 3.0 Icon standard and if the platform is able to navigate to and display the icon clickthrough URL, AdChoices support requires no further work.

If your platform is unable to navigate to and display clickthrough URLs—this primarily applies to devices that don't have an integrated web browser—you must implement support for the "IconFallbackImages" extension. This extension contains a set of "IconFallbackImages" tags where the "program" attribute matches an icon that was included in the VAST.

To fully support AdChoices, the IconFallbackImages tag with the program name "GoogleWhyThisAd" must be associated with the Icon with the program name "GoogleWhyThisAd", such that when the user interacts with the icon, the associated fallback image is displayed.

To support potential future changes to the AdChoices standard, we highly recommend incorporating fallback image support for all VAST Icons, when available. You can uses this sample VAST 3.0 xml for additional testing in your app.

IconFallbackImages Extension Structure

Tag	Attributes	Description
Extension	type	For this extension, the type always contains the value IconClickFallbackImages.
-IconClickFallbackImages	program	This attribute always matches the program attribute of an associated VAST 3.0 Icon.
		The structure of this node matches the VAST 4.2 standard for IconClickFallbackImages, except for the addition of the program attribute.
--IconClickFallbackImage	width	The preferred width to display the image.
	height	The preferred height to display the image.
---AltText		An accessible description of the image.
---StaticResource	creativeType	The mimetype of the fallback image.
		A CDATA value containing the URL of the fallback image.

Sample VAST 3.0 Response

<?xml version="1.0" encoding="UTF-8"?>
<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="3.0">
 <Ad id="123456">
  <InLine>
   ...
   <Creatives>
    ...
    <Creative id="7891011" AdID="ABCD123456EF" sequence="1">
     ...
     <Linear>
      ...
      <Icons>
       ...
       <Icon program="GoogleWhyThisAd" width="50" height="50" xPosition="20" yPosition="bottom" duration="00:00:10" offset="00:00:00" apiFramework="VAST" altText="Why This Ad?">
        <StaticResource creativeType="image/png">
         <![CDATA[https://storage.googleapis.com/interactive-media-ads/hosted-samples/wta/icon_adchoices.png]]>
        </StaticResource>
        <IconClicks>
         ...
         <IconClickThrough><![CDATA[https://g.co/adsettings]]></IconClickThrough>
        </IconClicks>
       </Icon>
       ...
      </Icons>
     ...
     </Linear>
     ...
    </Creative>
    ...
   </Creatives>
   <Extensions>
    ...
    <Extension type="IconClickFallbackImages">
     ...
     <IconClickFallbackImages program="GoogleWhyThisAd">
      <IconClickFallbackImage width="400" height="150">
       <AltText>Alt icon fallback</AltText>
       <StaticResource creativeType="image/png"><![CDATA[https://storage.googleapis.com/gvabox/nickchavez/media/png/wta_dialog.png]]></StaticResource>
      </IconClickFallbackImage>
      ...
     </IconClickFallbackImages>
     ...
    </Extension>
    ...
   </Extensions>
   ...
  </InLine>
  ...
 </Ad>
</VAST>

Parse AdChoices from DAI API metadata JSON

When working with the DAI API, AdChoices details are passed through the JSON object that is returned by requests to the metadata URL.

The Metadata JSON object contains a list of ads, keyed by the adID. Within each ad object is an icons array. If the ad in question utilizes AdChoices, the AdChoices icon is contained in that array.

Note: The AdChoices icon isn't served to streams utilizing Server Side Beaconing (SSB).

JSON icon format

The JSON icon format is a 1:1 translation from the VAST 4.2 icon standard (section 3.11), wherever possible. However, to support the more strict JSON format, some attributes have changed names, where necessary.

Icon JSON format

program	For the AdChoices icon, this value always contains the string, "GoogleWhyThisAd".
x_position	The horizontal position of the top left corner of the icon, relative to the top left corner of the video creative, in pixels. This field also accepts the responsive position values "right" or "left".
y_position	The vertical position of the top left corner of the icon, relative to the top left corner of the video creative, in pixels. This field also accepts the responsive position values "top" or "bottom".
width	The width of the icon, in pixels.
height	The height of the icon, in pixels.
creative_type	The mimetype of the image provided for the icon. Defaults to "image/png".
resource	The URL to retrieve the AdChoices icon.
alt_text	The alt text to render for the AdChoices icon.
click_data	An object containing the property click_data.url which represents the URL to direct viewers to if they click the AdChoices icon on a platform that supports web browsing.
click_fallback_images	An array of image objects to display to viewers who click the AdChoices icon on platforms that don't support web browsing.

Fallback Image JSON format

width	The width of the fallback image, in pixels.
height	The height of the fallback image, in pixels.
creative_type	The mimetype of the fallback image. Defaults to "image/png".
resource	The URL to retrieve the fallback image.
alt_text	The alt text to render for the fallback image.

Sample Metadata JSON

{
  ...
  "ads": {
    ...
    "0002640412_ad1": {
      ...
      "icons": [
        ...
        {
          "alt_text": "AdChoices icon",
          "click_data": {
            "url": "https://g.co/adsettings"
          },
          "click_fallback_images": [
            {
              "alt_text": "This ad was shown to you based on: * Google's estimation of your interests, based on your activity on Google on this device (for example, your searches) * the information on the website you were viewing.",
              "creative_type": "image/jpg",
              "height": 600,
              "resource": "https://storage.googleapis.com/interactive-media-ads/hosted-samples/wta/icon_adchoices_fallback_image.png",
              "width": 950
            }
          ],
          "creative_type": "image/png",
          "height": 30,
          "program": "AdChoices",
          "resource": "https://storage.googleapis.com/interactive-media-ads/hosted-samples/wta/icon_adchoices.png",
          "type": "static",
          "width": 40,
          "x_position": "0",
          "y_position": "100"
        }
        ...
      ]
      ...
    },
    ...
  }
  ...
}