“广告选择”图标和叠加层

所有展示由 Google 托管的个性化广告的应用都必须实现由 Google 提供的AdChoices图标和叠加层。“广告选择”（也称为“为什么显示该广告”）是一项透明度功能，可向用户说明他们为何会看到特定广告，并提供有关如何保护用户隐私的信息。

如需了解详情，请参阅为什么您会看到广告。

本指南介绍了如何从广告的 VAST XML 响应或 DAI 视频流的元数据响应中提取必要信息，以正确实现“广告选择”。

“广告选择”呈现的要求

为符合 Google 关于呈现“广告选择”图标的要求，您的应用或网站必须符合以下标准：

  1. “广告选择”图标必须显示在提供该图标的所有广告的上方
  2. “广告选择”图标必须在图标数据中包含的“X 位置”和“Y 位置”属性指示的位置显示，并且尺寸必须按照宽度和高度属性定义的尺寸（以密度无关像素 (DP) 为单位）。
  3. “广告选择”图标不得被其他广告叠加层或界面元素遮挡。
  4. 在支持点击功能或具有类似功能（例如轻触或远程选择）的平台上，“广告选择”图标必须是可点击的。
  5. 在支持浏览器的平台上，点击“广告选择”图标必须打开一个浏览器标签页或窗口，其中包含“ClickThrough”或“click_data”属性中指定的网址。
  6. 在不支持浏览器的平台上，点击“广告选择”图标必须打开一个模态叠加层，以显示“IconClickFallbackImage”或“click_fallback_images”属性中指定的某张图片。
  7. 在不支持浏览器的平台上，回退图片必须以“IconClickFallbackImage”或“click_fallback_images”属性中指定的尺寸显示（采用密度无关像素 (DP)）。

解析 VAST XML 响应中的广告选择

处理 XML 广告响应时，只有 VAST 3.0 及更高版本支持“广告选择”。广告选择以 VAST 图标的形式实现。

VAST 4.2

如果您的 XML 广告响应符合 VAST 4.2 标准，则“广告选择”将以 VAST 图标的形式投放。如果您的应用或网站完全支持 VAST 4.2 图标（VAST 4.2 标准第 3.11 节），“广告选择”支持就无需执行进一步操作。

如果您的应用不支持 VAST 4.2 图标，您需要根据该标准手动解析 VAST 响应中计划名称为“GoogleWhyThisAd”的图标。您可以使用此示例 VAST 4.2 xml 在您的应用中进行其他测试。

VAST 4.2 响应示例

<?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

如果您的 XML 广告响应遵循 VAST 3.0 标准，则系统会将“广告选择”作为 VAST 图标和自定义 VAST 扩展程序的组合进行投放。如果您的应用或网站完全支持 VAST 3.0 图标标准，并且相应平台能够导航到并显示该图标的点击后到达网址，则无需进一步支持“广告选择”支持。

如果您的平台无法导航到并显示点击后到达网址（这主要适用于未集成网络浏览器的设备），则必须实现对“IconFallbackImages”扩展程序的支持。此扩展程序包含一组“IconFallbackImages”代码，其中“program”属性与 VAST 中包含的一个图标相匹配。

为了全面支持“广告选择”，计划名称为“GoogleWhyThisAd”的 IconFallbackImages 代码必须与计划名称为“GoogleWhyThisAd”的图标相关联，以便在用户与图标互动时，系统会显示关联的后备图片。

为支持未来对“广告选择”标准可能做出的更改，我们强烈建议您为所有 VAST 图标添加后备图片支持（如果可用）。您可以使用此示例 VAST 3.0 xml 在您的应用中进行其他测试。

IconFallbackImages 扩展结构

添加链接 属性 说明
扩展程序 type 对于此扩展程序，类型始终包含值 IconClickFallbackImages。
-IconClickFallbackImages 节目 此属性始终与相关 VAST 3.0 图标的节目属性匹配。
除了添加了 program 属性之外，此节点的结构符合 IconClickFallbackImages 的 VAST 4.2 标准。
--IconClickFallbackImage 宽度 显示图片的首选宽度。
高度 用于显示图片的首选高度。
---AltText 图片的可访问说明。
---StaticResource creativeType 后备图片的 MIME 类型。
包含后备图片网址的 logcat 值。

VAST 3.0 响应示例

<?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>

从 DAI API 元数据 JSON 解析广告选择

使用 DAI API 时，系统会通过向元数据网址的请求返回的 JSON 对象传递“广告选择”详细信息。

元数据 JSON 对象包含由 adID 键控的广告列表。每个广告对象中都有一个图标数组。如果相关广告使用的是“广告选择”，“广告选择”图标会包含在该数组中。

JSON 图标格式

尽可能采用 JSON 图标格式根据 VAST 4.2 图标标准（第 3.11 节）进行 1:1 转换。不过，为了支持更严格的 JSON 格式，某些属性会在必要时更改名称。

图标 JSON 格式

节目 对于“广告选择”图标，此值始终包含字符串“GoogleWhyThisAd”。
x_position 图标左上角相对于视频广告素材左上角的水平位置（以像素为单位）。此字段还接受自适应位置值“right”或“left”。
y_position 图标左上角的垂直位置（相对于视频广告素材的左上角，以像素为单位）。此字段还接受自适应位置值“top”或“bottom”。
宽度 图标的宽度（以像素为单位）。
高度 图标的高度（以像素为单位）。
creative_type 为图标提供的图片的 MIME 类型。默认值为“image/png”。
资源 用于检索“广告选择”图标的网址。
alt_text 要为“广告选择”图标呈现的替代文本。
click_data 一个对象，包含属性 click_data.url，当观看者在支持网页浏览的平台上点击“广告选择”图标时，此属性表示观看者会被定向到的网址。
click_fallback_images 向在不支持网页浏览的平台上点击“广告选择”图标的观看者显示的一组图片对象。

后备图片 JSON 格式

宽度 后备图片的宽度（以像素为单位）。
高度 后备图片的高度（以像素为单位）。
creative_type 后备图片的 MIME 类型。默认值为“image/png”。
资源 用于检索后备图片的网址。
alt_text 要为后备图片呈现的替代文本。

示例元数据 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"
        }
        ...
      ]
      ...
    },
    ...
  }
  ...
}