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 广告中的其他元素公开 “exit” 操作。

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

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

配置规范

有关配置规范，请参阅 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"
    }
  }
}

点击跟踪 URL

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

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

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

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

变量替换

变量替换适用于导航 URL 和点击跟踪 URL。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 操作调用中覆盖默认值。

变量值也可以来自 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 元素维护的状态变量。它们可以在运行时更新，以启用有状态的退出行为。

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

exit

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

名称	值	含义
`target`	字符串	状态变量的名称。
`variable`	字符串	`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 验证器规范，请阅读 amp-ad-exit 规则。

需要更多帮助？

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

转到 Stack Overflow

发现错误或缺少功能？

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

转到 GitHub