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

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`	數字	與頂端邊緣的距離 (以像素為單位)。指定即可覆寫預設值 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"
    }
  }
}

點擊追蹤網址

導覽目標可以與設定中的點擊追蹤網址建立關聯。在導覽之前，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 動作調用中的預設值。

變數值也可以來自第三方分析。使用 <amp-analytics type='example-3p-vendor'> 安裝第三方分析供應商 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`	字串	狀態變數的名稱。
`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_-]+`	字串、布林值或數字	以這個名稱和值取代最終網址和追蹤網址中的網址參數。

注意：當您觸發跳出動作時，應提供目標或變數，但不得兩者都提供。

範例

<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