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