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`	數字	以毫秒為單位，拒絕在進入viewport 後的任何點擊。
`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`	提供使用者代理程式用戶端提示資訊。警告：由於 UACH API 是非同步的，而 amp-ad-exit 僅為同步，因此若要擷取 UACH 信號，必須事先由另一個也使用變數替換的 AMP 元件擷取並快取值，否則這些值將為空。

自訂變數

自訂變數必須以下底線開頭。在設定中與導覽目標一起定義變數。變數應具有 `\"defaultValue\"` 屬性。您可以在 `exit` 動作叫用中覆寫預設值。

變數值也可以來自第三方分析。使用安裝第三方分析供應商 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` 也支援變數目標。變數目標本身不會定義退出網址。相反地，它們指向 `ExitConfig` 中具名的 `NavigationTarget`。請勿將這些與 URL 自訂變數混淆。這些是由 `amp-ad-exit` 元素維護的狀態變數。可以在執行階段更新它們，以啟用具狀態的退出行為。

名稱	值	意義
`名稱`	字串	狀態變數的名稱。
`目標`	字串	此狀態變數指向的 `ExitConfig` 中的 `NavigationTarget` 名稱。

exit

`amp-ad-exit` 元素公開一個 `exit` 動作，其他元素會在 `on=\"tap:...\" 屬性` 中參考該動作。此動作接受 `\"target\"` 字串參數 (必須符合 `ExitConfig` 中具名的 `NavigationTarget`)，或 `\"variable\"` 字串參數 (是狀態變數，指向 `NavigationTarget`)。也可以傳入以下底線開頭的自訂變數。

名稱	值	意義
`目標`	字串	狀態變數的名稱。
`變數`	字串	此狀態變數指向的 `ExitConfig` 中的 `NavigationTarget` 名稱。
default`	字串	當狀態變數未設定時，狀態變數應指向的預設 `NavigationTarget` 名稱。這僅在變數使用時才有意義。
`_[a-zA-Z0-9_-]+`	字串、布林值或數字	使用此名稱和值取代最終和追蹤網址中的 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