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 点击跟踪 URL。
在新标签页中打开目标 URL。

配置规范

请参阅 config.js 中的 AmpAdExitConfig 类型定义，以获取配置规范。

过滤器

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

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

clickLocation 过滤器

clickLocation 过滤器指定点击距离创意边缘或创意中特定元素边缘的最小距离。clickLocation 过滤器可能有以下属性

属性	值	含义
`top`	数字	距离顶部边缘的 px 数。指定以覆盖默认值 0。
`right`	数字	距离右边缘的 px 数。指定以覆盖默认值 0。
`bottom`	数字	距离底部边缘的 px 数。指定以覆盖默认值 0。
`left`	数字	距离左边缘的 px 数。指定以覆盖默认值 0。
`relativeTo`	字符串	选择用于边缘边界的元素。如果未指定，则默认使用创意的完整 `body`。选定的元素不必是触发退出的元素。选定的元素在创意的生命周期中必须处于固定位置。选择器必须使用 CSS 选择器语法。

clickDelay 过滤器

clickDelay 过滤器类型指定在响应点击之前等待的时间量。请记住，amp-ad-exit 对所有退出施加了 1 秒的最小延迟。

clickDelay 过滤器需要以下属性

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

注意：默认的 1 秒点击延迟使用扩展加载时间作为间隔。但是，可以覆盖此设置以使用 `startTimingEvent` 值。为此，请使用 config 根目录中的 `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` 过滤器需要以下属性

属性	值	说明
`选择器`	字符串	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"
    }
  }
}

点击跟踪网址

导航目标可以与 config 中的点击跟踪网址关联。在导航之前，`amp-ad-exit` 会尝试使用以下内容来 ping 跟踪网址

如果可用，则为 `navigator.sendBeacon`
图像请求

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

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

变量替换

变量替换适用于导航网址和点击跟踪网址。网址变量替换的工作原理与标准 AMP 变量替换相同，具有自定义变量和一组有限的平台变量。

平台变量

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

自定义变量

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

变量值也可以来自 3P 分析。使用 <amp-analytics type='example-3p-vendor'> 安装 3P 分析供应商 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 元素维护的状态变量。它们可以在运行时更新，以启用有状态的退出行为。

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

退出

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

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

注意：触发退出操作时，应提供目标或变量，但不能同时提供。

示例

<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-ad-exit 规则，了解 AMP 验证器规范。

需要更多帮助？

您已经阅读了本文档十几次，但它并没有真正涵盖您的所有问题？也许其他人也有同感：在 Stack Overflow 上联系他们。

转到 Stack Overflow

发现错误或缺少功能？

AMP 项目强烈鼓励您参与和做出贡献！我们希望您成为我们开源社区的持续参与者，但我们也欢迎您对特别感兴趣的问题做出一次性贡献。

转到 GitHub