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 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 选择器。如果触发退出的事件的“目标”与选择器匹配，则不会执行退出。

示例

{
  "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 参数。

注意：当您触发退出操作时，应提供 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