The DAI API is in Beta and might not be available in your network. Contact your account manager for more information. The IMA SDK is recommended for platforms where it is available.

Rendering the AdChoices icon and overlay

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.

Rendering requirements for AdChoices

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).

Parsing AdChoices from a VAST XML response

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

VAST 4.2

If your XML ad response follows the VAST 4.2 standard, AdChoices will be 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), you will have AdChoices support without any additional work.

If your application 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 uses 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 will be 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, you will have AdChoices support without any additional work.

If your platform is unable to navigate to and display clickthrough urls (this primarily applies to devices that do not have an integrated web browser), you will need to implement support for the "IconFallbackImages" extension. This extension will contain a set of "IconFallbackImages" tags where the "program" attribute will match 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 will be 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 will always contain the value "IconClickFallbackImages".
-IconClickFallbackImages program This attribute will always match the program attribute of an associated VAST 3.0 Icon.
The structure of this node will match 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>

Parsing AdChoices from DAI API metadata JSON

When working with the DAI API, AdChoices details will be passed via 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 will be contained in that array.

Understanding the icon JSON 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 will always contain 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 do not 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"
        }
        ...
      ]
      ...
    },
    ...
  }
  ...
}