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.
Requirements for AdChoices rendering
To comply with Google's requirements for rendering AdChoices icons, your app or website must meet the following standards:
- The AdChoices icon must be displayed overlaying any ad for which it is provided
- 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).
- The AdChoices icon must not be obscured by other ad overlays or interface elements.
- On platforms with click support or equivalent (e.g. touch or remote select), the AdChoices icon must be clickable.
- 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.
- 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.
- 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
IconClickFallbackImages
.program
attribute.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.
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"
}
...
]
...
},
...
}
...
}
