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

所有展示由 Google 托管的个性化广告的应用都必须实现 AdChoices 图标和叠加层（如果 Google 提供）。“广告选项”（也称为“为什么显示该广告？”）是一项透明度功能，旨在向用户说明系统为何向其展示特定广告，并提供相关信息以便用户了解其隐私会受到怎样的保护。

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

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

“广告选项”图标的呈现要求

为遵守 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 响应中解析 AdChoices

使用 XML 广告响应时，AdChoices 仅在 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”的 Icon 相关联，这样当用户与该图标互动时，系统就会显示关联的后备图片。

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

IconFallbackImages 扩展程序结构

标记 属性 说明
扩展程序 type 对于此扩展程序，类型始终包含值 IconClickFallbackImages。
-IconClickFallbackImages 计划 此属性始终与关联的 VAST 3.0 图标的程序属性相匹配。
此节点的结构与 VAST 4.2 标准中的 IconClickFallbackImages 结构相符，只是添加了 program 属性。
--IconClickFallbackImage width 显示图片的理想宽度。
身高 显示图片的理想高度。
---AltText 图片的无障碍说明。
---StaticResource creativeType 后备图片的 MIME 类型。
包含后备图片网址的 CDATA 值。

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 中解析 AdChoices

使用 DAI API 时，AdChoices 详细信息会通过对元数据网址的请求返回的 JSON 对象传递。

元数据 JSON 对象包含一个广告列表，该列表按 adID 设置键。每个广告对象中都有一个图标数组。如果相关广告使用“广告选项”，则该数组中包含“广告选项”图标。

JSON 图标格式

JSON 图标格式尽可能地从 VAST 4.2 图标标准（第 3.11 节）直接转换而来。不过，为了支持更严格的 JSON 格式，我们根据需要更改了一些属性的名称。

图标 JSON 格式

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

后备图片 JSON 格式

width 后备图片的宽度（以像素为单位）。
身高 后备图片的高度（以像素为单位）。
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"
        }
        ...
      ]
      ...
    },
    ...
  }
  ...
}