重要事項：本文件不適用於您目前選取的格式 stories！

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 元件。使用此元件註解其他元素，以便在輕觸時結束，並將目標名稱和額外的網址參數傳遞至使用者的瀏覽器。結束動作會執行下列步驟：

如果尚未剖析 JSON 設定，則剖析該設定。
尋找要求的結束目標。
透過宣告的篩選器處理點擊事件，以判斷是否應允許結束。
改寫網址變數。
Ping (發送訊號) 點擊追蹤網址。
在新分頁中開啟目標網址。

設定規格

請參閱 config.js 中的 AmpAdExitConfig typedef 以取得設定規格。

篩選器

您可以在設定的 filters 區段中指定篩選器。然後，您可以依篩選器在 filters 區段中的屬性名稱來參照這些篩選器。

主要有三種篩選器類型：位置型、時間型和元素型。其他篩選器 (例如確認提示) 可以視需要新增。

clickLocation 篩選器

clickLocation 篩選器指定點擊位置與廣告素材邊緣或廣告素材中特定元素邊緣的最小距離。clickLocation 篩選器可能具有下列屬性：

屬性	值	意義
`top (上方)`	number (數字)	與頂端邊緣的距離 (以像素為單位)。指定此屬性可覆寫預設值 0。
`right (右方)`	number (數字)	與右側邊緣的距離 (以像素為單位)。指定此屬性可覆寫預設值 0。
`bottom (下方)`	number (數字)	與底部邊緣的距離 (以像素為單位)。指定此屬性可覆寫預設值 0。
`left (左方)`	number (數字)	與左側邊緣的距離 (以像素為單位)。指定此屬性可覆寫預設值 0。
`relativeTo (相對位置)`	string (字串)	選取用於邊緣邊界的元素。如果未指定，預設會使用廣告素材的完整 `body`。選取的元素不一定要是觸發結束的元素。選取的元素在廣告素材的生命週期中必須處於固定位置。選取器必須使用 CSS 選取器語法。

clickDelay 篩選器

clickDelay 篩選器類型指定在回應點擊之前要等待的時間量。請記住，amp-ad-exit 對所有結束動作都強制執行至少 1 秒的延遲。

clickDelay 篩選器需要下列屬性：

屬性	值	意義
`delay (延遲)`	number (數字)	拒絕在進入可視區域後任何點擊的時間 (以毫秒為單位)。
`startTimingEvent`	string (字串)	要用作延遲開始間隔的事件名稱，例如 `navigationStart`。根據 window performance timing (視窗效能計時)。

注意：預設的 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 (選取器)`	string (字串)	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,
  }
}

變數替換

變數替換適用於導覽網址和點擊追蹤網址。網址變數替換的運作方式與標準 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
>

注意：請小心您的變數名稱。替換是透過簡單的字串取代來運作。網址中出現的任何變數都會被取代。例如，如果您定義一個名為 "_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。請勿將這些與網址自訂變數混淆。這些是由 amp-ad-exit 元素維護的狀態變數。它們可以在執行階段更新，以啟用具狀態的結束行為。

名稱	值	意義
`name (名稱)`	string (字串)	狀態變數的名稱。
`target (目標)`	string (字串)	`ExitConfig` 中 `NavigationTarget` 的名稱，此狀態變數指向該目標。

exit (結束)

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

名稱	值	意義
`target (目標)`	string (字串)	狀態變數的名稱。
`variable (變數)`	string (字串)	`ExitConfig` 中 `NavigationTarget` 的名稱，此狀態變數指向該目標。
default` (預設)	string (字串)	狀態變數未設定時應指向的預設 `NavigationTarget` 的名稱。這僅在變數使用時才有意義。
`_[a-zA-Z0-9_-]+`	string (字串)、boolean (布林值) 或 number (數字)	使用此名稱和值取代最終網址和追蹤網址中的網址參數。

注意：當您觸發結束動作時，應提供目標或變數，但不能同時提供兩者。

範例

<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