重要提示：此文档不适用于您当前选择的格式 email！

amp-ad-exit

描述

为 AMPHTML 广告提供可配置的广告退出行为。

必需脚本

<script async custom-element="amp-ad-exit" src="https://cdn.ampproject.org/v0/amp-ad-exit-0.1.js"></script>

支持的布局

nodisplay container

为 AMPHTML 广告提供可配置的广告退出行为。

用法

使用 amp-ad-exit 组件向 AMPHTML 广告中的其他元素公开“退出”操作。

使用 JSON 子脚本元素配置 amp-ad-exit 组件。使用该组件来注解其他元素，使其在点击时退出，并将目标名称和额外的 URL 参数传递给用户的浏览器。退出操作执行以下步骤

如果 JSON 配置尚未解析，则解析该配置。
查找请求的退出目标。
通过声明的筛选器处理点击事件，以确定是否允许退出。
重写 URL 变量。
Ping 点击跟踪网址。
在新选项卡中打开目标网址。

配置规范

有关配置规范，请参阅 config.js 中的 AmpAdExitConfig typedef。

筛选器

您可以在配置的 filters 部分中指定筛选器。然后，您可以在 filters 部分中通过其属性名称引用这些筛选器。

筛选器主要有三种类型：基于位置的、基于时间的和基于元素的。可以根据需要添加其他筛选器，例如确认提示。

clickLocation 筛选器

clickLocation 筛选器指定点击位置与广告素材边缘或广告素材中特定元素的边缘之间的最小距离。clickLocation 筛选器可能具有以下属性

属性	值	含义
`top`	数字	与顶部边缘的距离（以像素为单位）。指定以覆盖默认值 0。
`right`	数字	与右侧边缘的距离（以像素为单位）。指定以覆盖默认值 0。
`bottom`	数字	与底部边缘的距离（以像素为单位）。指定以覆盖默认值 0。
`left`	数字	与左侧边缘的距离（以像素为单位）。指定以覆盖默认值 0。
`relativeTo`	字符串	选择要用于边缘边界的元素。如果未指定，则默认情况下使用广告素材的整个 `body`。所选元素不需要是触发退出的元素。所选元素必须在广告素材的整个生命周期内处于固定位置。选择器必须使用 CSS 选择器语法。

clickDelay 筛选器

clickDelay 筛选器类型指定在响应点击之前要等待的时间量。请记住，amp-ad-exit 对所有退出操作强制执行至少 1 秒的延迟。

clickDelay 筛选器需要以下属性

属性	值	含义
`delay`	数字	进入视口后拒绝任何点击的时间（以毫秒为单位）。
`startTimingEvent`	字符串	要用作延迟开始间隔的事件名称，例如 `navigationStart`。基于窗口性能计时。

注意：默认的 1 秒点击延迟使用扩展加载时间作为间隔。但是，可以覆盖此设置以使用 startTimingEvent 值。为此，请使用配置根目录中的 options 对象。如果未显式给出值，则所有其他点击筛选器都会使用 startTimingEvent。

示例

在以下示例中，默认点击保护会从 navigationStart 施加 1 秒的延迟，并且另外指定了两个点击保护，即从 navigationStart 开始延迟 2 秒，以及从 DOMContentLoaded 开始延迟 3 秒。

<amp-ad-exit id="exit-api">
  <script type="application/json">
    {
      "targets": {
        "flour": {
          "finalUrl": "https://adclickserver.example.com/click?id=af319adec901&x=CLICK_X&y=CLICK_Y&adurl=https://example.com/artisan-baking/flour",
          "filters": ["3sClick", "2sClick"]
        }
      },
      "options": {
        "startTimingEvent": "navigationStart"
      },
      "filters": {
        "3sClick": {
          "type": "clickDelay",
          "delay": 3000,
          "startTimingEvent": "domContentLoadedEventStart"
        },
        "2sClick": {
          "type": "clickDelay",
          "delay": 2000
        }
      }
    }
  </script>
</amp-ad-exit>

inactiveElement 筛选器

inactiveElement 筛选器类型指定不应在事件源时导致退出的元素。请记住，默认情况下，amp-ad-exit 会忽略对 amp-carousel 的上一个和下一个按钮的点击。

inactiveElement 筛选器需要以下属性

属性	值	描述
`selector`	字符串	CSS 选择器。如果触发退出的事件的 `target` 与选择器匹配，则不会执行退出。

示例

{
  "targets": {
    "ad": {
      "finalUrl": "...",
      "filters": ["2second", "huge-border"]
    }
  },
  "filters": {
    "2second": {
      "type": "clickDelay",
      "delay": 2000
    },
    "small-border": {
      "type": "clickLocation",
      "top": 5,
      "right": 5,
      "bottom": 5,
      "left": 5
    },
    "huge-border": {
      "type": "clickLocation",
      "top": 100,
      "right": 100,
      "bottom": 100,
      "left": 100
    },
    "border-with-relative-to-element": {
      "type": "clickLocation",
      "top": 10,
      "right": 10,
      "bottom": 10,
      "left": 10,
      "relativeTo": "#headline"
    }
  }
}

点击跟踪网址

导航目标可以在配置中与点击跟踪网址相关联。在导航之前，amp-ad-exit 尝试使用以下方式来 Ping 跟踪网址

navigator.sendBeacon（如果可用）
图像请求

您可以使用配置上的 "transport" 对象覆盖此行为，例如在本示例中

{
  "targets": { ... },
  "filters": { ... },
  "transport": {
    "beacon": false,
  }
}

变量替换

变量替换适用于导航网址和点击跟踪网址。URL 变量替换的工作方式类似于标准的 AMP 变量替换，其中包含自定义变量和一组有限的平台变量。

平台变量

名称	值
`RANDOM`	一个随机浮点数。
`CLICK_X`	视口中点击的 `x` 坐标。
`CLICK_Y`	视口中点击的 `y` 坐标。
`UACH`	提供 [用户代理客户端提示](https://github.com/WICG/ua-client-hints) 信息。警告：由于 UACH API 是异步的，而 amp-ad-exit 仅是同步的，因此要检索 UACH 信号，必须预先由另一个也使用变量替换的 AMP 组件检索并缓存这些值，否则它们将为空。

自定义变量

自定义变量必须以下划线开头。在配置中与导航目标一起定义变量。变量应具有 "defaultValue" 属性。您可以在 exit 操作调用中覆盖默认值。

变量值也可以来自第三方分析。使用 <amp-analytics type='example-3p-vendor'> 安装第三方分析供应商 iframe，并在变量定义中使用 "iframeTransportSignal" 属性引用它。"iframeTransportSignal" 的格式为 "IFRAME_TRANSPORT_SIGNAL(example-3p-vendor,collected-data)"，其中 example-3p-vendor 是供应商的名称，而 collected-data 是来自供应商 iframe 的消息中的键。请勿在两者之间的逗号后添加空格。

按照惯例，用户定义的变量应采用 _camelCase 格式，系统变量应采用 ALL_CAPS 格式。

<amp-ad-exit id="exit-api"
  ><script type="application/json">
    {
      "targets": {
        "product": {
          "finalUrl": "http://example.com/?page=_productCategory&verification=_3pAnalytics",
          "vars": {
            "_productCategory": {
              "defaultValue": "none"
            },
            "_3pAnalytics": {
              "defaultValue": "no_response",
              "iframeTransportSignal": "IFRAME_TRANSPORT_SIGNAL(example-3p-vendor,collected-data)"
            }
          }
        }
      }
    }
  </script></amp-ad-exit
>
<a on="tap:exit-api.exit(target='product', _productCategory='shoes')"
  >buy shoes</a
>
<a on="tap:exit-api.exit(target='product', _productCategory='hats')"
  >buy hats</a
>

注意：请小心使用变量名称。替换是通过简单的字符串替换进行的。URL 中出现的任何变量都会被替换。例如，如果您定义了一个名为 "_b" 的自定义变量，其值为 "foo"，则 /?a_b_c=_b 将变为 /?afoo_c=foo。

行为

行为指定 exit 操作的其他属性。

clickTarget

clickTarget 行为指定目标点击应尝试在何处打开。如果环境允许，点击默认在新选项卡中打开。如果设置为 "_top"，则用户可以指定点击应在同一选项卡中打开。如果设置为除 "_top" 以外的任何值，则会在新选项卡中打开。

示例

<amp-ad-exit id="exit-api">
  <script type="application/json">
    {
      "targets": {
        "landingPage": {
          "finalUrl": "https://example.com/artisan-baking/?from=_clickArea",
          "vars": {
            "_clickArea": {
              "defaultValue": "headline"
            }
          }
        },
        "flour": {
          "finalUrl": "https://adclickserver.example.com/click?id=af319adec901&x=CLICK_X&y=CLICK_Y&adurl=https://example.com/artisan-baking/flour",
          "filters": ["3sClick", "borderProtection"],
          "behaviors": {
            "clickTarget": "_top"
          }
        },
        "bannetons": {
          "finalUrl": "https://example.com/artisan-baking/bannetons",
          "trackingUrls": [
            "https://adclickserver.example.com/click?id=af319adec901&x=CLICK_X&y=CLICK_Y",
            "https://tracker.adnetwork.example.com/?url=example.com"
          ],
          "filters": ["3sClick", "borderProtection"]
        }
      },
      "filters": {
        "3sClick": {
          "type": "clickDelay",
          "delay": 3000
        },
        "borderProtection": {
          "type": "clickLocation",
          "top": 10,
          "right": 10,
          "bottom": 10,
          "left": 10
        }
      }
    }
  </script>
</amp-ad-exit>

<h1 on="tap:exit-api.exit(target='landingPage')">Artisan Baking Supplies</h1>
<div id="product0" on="tap:exit-api.exit(target='flour')">
  <p>Rye flour</p>
  <amp-img src="..." width="..." height="..."></amp-img>
</div>
<div id="product1" on="tap:exit-api.exit(target='bannetons')">
  <p>Bannetons</p>
  <amp-img src="..." width="..." height="..."></amp-img>
</div>
<div
  id="footer"
  on="tap:exit-api.exit(target='landingPage', _clickArea='footer')"
>
  example.com/artisan-baking
</div>

属性

Id

需要一个 id，以便可点击的元素可以引用 amp-exit。

操作

setVariable

amp-ad-exit 还支持变量目标。变量目标本身不定义退出 URL。相反，它们指向 ExitConfig 中的命名 NavigationTarget。不要将它们与 URL 自定义变量混淆。这些是 amp-ad-exit 元素维护的状态变量。它们可以在运行时更新，以启用有状态的退出行为。

名称	值	含义
`name`	字符串	状态变量的名称。
`target`	字符串	此状态变量指向的 `ExitConfig` 中的 `NavigationTarget` 的名称。

exit

amp-ad-exit 元素公开了一个 exit 操作，其他元素在 on="tap:..." attributes 中引用该操作。该操作接受一个 "target" 字符串参数，该参数必须与 ExitConfig 中的命名 NavigationTarget 匹配，或接受一个 "variable" 字符串参数，该参数是一个指向 NavigationTarget 的状态变量。还可以传入以下划线开头的自定义变量。

名称	值	含义
`target`	字符串	状态变量的名称。
`variable`	字符串	此状态变量指向的 `ExitConfig` 中的 `NavigationTarget` 的名称。
default`	字符串	状态变量未设置时应指向的默认 `NavigationTarget` 的名称。这仅在变量被使用时才有意义。
`_[a-zA-Z0-9_-]+`	字符串、布尔值或数字	使用此名称和值替换最终 URL 和跟踪 URL 中的 URL 参数。

注意：触发退出操作时，应提供 target 或 variable，但不能同时提供两者。

示例

<amp-ad-exit id="exit-api" layout="nodisplay">
  <script type="application/json">
    {
      "targets": {
        "product1": {
          "finalUrl": "https://example.com/product1"
        },
        "product2": {
          "finalUrl": "https://example.com/product2"
        }
      }
    }
  </script>
</amp-ad-exit>
<amp-selector
  id="exit-selector"
  layout="nodisplay"
  on="select:exit-api.setVariable(name='currentProduct', target=event.targetOption)"
>
  <option option="product1" selected></option>
  <option option="product2"></option>
</amp-selector>
<amp-carousel
  type="slides"
  autoplay
  on="slideChange:exit-selector.toggle(index=event.index, value=true),
        tap:exit-api.exit(variable='currentProduct', default='product1')"
>
  <div>product 1</div>
  <div>product 2</div>
</amp-carousel>

验证

amp-ad-exit 元素仅适用于 AMPHTML 广告。有关 AMP 验证器规范，请阅读 amp-ad-exit 规则。

需要更多帮助吗？

您已经阅读这份文档很多遍了，但它并没有真正涵盖您所有的问题？也许其他人也有同样的感受：在 Stack Overflow 上联系他们。

前往 Stack Overflow

发现了一个错误或缺少某个功能？

AMP 项目强烈鼓励您的参与和贡献！我们希望您能成为我们开源社区的长期参与者，但也欢迎您针对自己特别感兴趣的问题进行一次性贡献。

前往 GitHub