All apps that display ads that Google hosts must implement the
[AdChoices](https://support.google.com/My-Ad-Center-Help/answer/12155764) 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 details, see
[AdChoices for Google Ad Manager](https://support.google.com/admanager/answer/2695279).

For more information, see [Why you're seeing an
ad](https://support.google.com/My-Ad-Center-Help/answer/12155764).

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]
> **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](https://iabtechlab.com/wp-content/uploads/2019/06/VAST_4.2_final_june26.pdf),
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](https://storage.googleapis.com/interactive-media-ads/ad-tags/ima_wta_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](https://www.iab.com/wp-content/uploads/2015/06/VASTv3_0.pdf), 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](https://storage.googleapis.com/interactive-media-ads/ad-tags/ima_wta_sample_vast_3.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. |
| -IconClickFallbackImages |   | 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. |
| --IconClickFallbackImage | height | The preferred height to display the image. |
| ---AltText |   | An accessible description of the image. |
| ---StaticResource | creativeType | The mimetype of the fallback image. |
| ---StaticResource |   | 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](https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service), AdChoices details are
passed through the JSON object that is returned by requests to the [metadata
URL](https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/video-player-live#poll-metadata).

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]
> **Note:** The AdChoices icon isn't served to streams utilizing [Server Side
> Beaconing (SSB)](https://support.google.com/admanager/answer/7299051).

### JSON icon format

The JSON icon format is a 1:1 translation from the [VAST 4.2 icon
standard](https://iabtechlab.com/wp-content/uploads/2019/06/VAST_4.2_final_june26.pdf)
(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"
            }
            ...
          ]
          ...
        },
        ...
      }
      ...
    }