amp-analytics

<script async custom-element="amp-analytics" src="https://cdn.ampproject.org/v0/amp-analytics-0.1.js"></script>

用法

<amp-analytics> 元件指定一個 JSON 設定物件，其中包含要評估的項目以及將分析資料傳送至何處的詳細資訊。它可以回報給內部或整合的第三方解決方案。

<amp-analytics> 的設定物件使用以下格式

{
  "requests": {
    "request-name": request-value,
    ...
  },
  "vars": {
    "var-name": var-value,
    ...
  },
  "extraUrlParams": {
    "extraurlparam-name": extraurlparam-value,
    ...
  },
  "triggers": {
    "trigger-name": trigger-object,
    ...
  },
  "transport": {
    "beacon": *boolean*,
    "xhrpost": *boolean*,
    "image": *boolean*,
  }
}

設定資料可以內嵌指定，也可以透過在 config 屬性中指定網址來遠端擷取。此外，也可以使用 type 屬性來選取熱門分析供應商的內建設定。

如果使用了多個來源的設定資料，設定物件 (vars、requests 和 triggers) 將會合併在一起，使得

1. 遠端設定優先於內嵌設定，且
2. 內嵌設定優先於供應商設定。

在您的網站上開始使用 AMP 分析之前，您需要決定是否要使用第三方分析工具來分析使用者互動，還是使用您自己的內部解決方案。

將資料傳送給分析供應商

amp-analytics 元件專門設計為「評估一次，回報多次」。如果您已經與一個或多個分析供應商合作，請查看分析供應商清單，看看他們是否已將其解決方案與 AMP 整合。

整合的分析供應商

對於整合的 AMP 分析供應商

1. 在 <amp-analytics> 標記中，新增 type 屬性，並將其值設定為指定的供應商。
2. 判斷您想要擷取和追蹤哪些資料，並在設定資料中指定這些詳細資訊。如需瞭解如何擷取分析資料的指示，請參閱供應商的文件。

在以下範例中，分析資料會傳送給 Nielsen (尼爾森)，這是一家已與 AMP 整合的第三方分析供應商。如需設定 Nielsen 分析資料的詳細資訊，請參閱 Nielsen 文件。

<amp-analytics type="nielsen">
  <script type="application/json">
    {
      "vars": {
        "apid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "apv": "1.0",
        "apn": "My AMP Website",
        "section": "Entertainment",
        "segA": "Music",
        "segB": "News",
        "segC": "Google AMP"
      }
    }
  </script>
</amp-analytics>

未整合的分析供應商

如果分析供應商尚未與 AMP 整合，請聯絡該供應商以尋求他們的支援。我們也鼓勵您提交問題，告知我們並要求新增該供應商。另請參閱在 AMP HTML 中整合您的分析工具。或者，與您的供應商合作，將資料傳送至他們指定的網址。如要瞭解詳情，請參閱下方的內部傳送資料章節。

內部傳送資料

如果您有自己的內部解決方案來評估使用者互動，那麼將 AMP 分析與該解決方案整合的唯一需求就是網址。您將在此處傳送資料。您也可以將資料傳送至各種網址。例如，您可以將網頁瀏覽資料傳送至一個網址，並將社群互動資料傳送至另一個網址。

如要將資料傳送至特定網址

1. 判斷您想要擷取和追蹤哪些資料，並在設定資料中指定這些詳細資訊。
2. 在requests 設定物件中，指定要追蹤的要求類型 (例如，網頁瀏覽、特定觸發事件) 以及您要將追蹤資料傳送至的網址。

以下範例追蹤網頁瀏覽次數。每當網頁可見時，就會觸發觸發事件，並將網頁瀏覽資料連同隨機 ID 傳送至定義的網址。

<amp-analytics>
  <script type="application/json">
    {
      "requests": {
        "pageview": "https://foo.com/pixel?RANDOM"
      },
      "triggers": {
        "trackPageview": {
          "on": "visible",
          "request": "pageview"
        }
      }
    }
  </script>
</amp-analytics>

載入遠端設定

如要載入遠端設定，請在 <amp-analytics> 元素中，指定 config 屬性和設定資料的網址。指定的網址應使用 HTTPS 配置。網址可能包含 AMP 網址變數。如要存取 Cookie，請參閱 data-credentials 屬性。回應必須遵循 AMP CORS 安全性指南。

在此範例中，我們指定 config 屬性以從指定的網址載入設定資料。

<amp-analytics
  config="https://example.com/analytics.account.config.json"
></amp-analytics>

動態改寫設定

設定改寫器功能旨在讓分析供應商能夠動態改寫提供的設定。這與遠端設定功能類似，但額外包含伺服器要求的任何使用者提供的設定。目前只有分析供應商可以啟用此功能。

分析供應商指定具有伺服器網址的 configRewriter 屬性。

export const VENDOR_ANALYTICS_CONFIG = {
    ...
    'configRewriter': {
      'url': 'https://www.vendor.com/amp-config-rewriter',
    },
    ...
}

AMP 將包含內嵌設定的要求 (與提供的遠端設定合併) 傳送至供應商提供的 configRewriter 端點。供應商使用此伺服器端資料來建構並傳回新的改寫設定。

然後，AMP 會合併所有提供的設定，以決定最終設定的優先順序，從最高到最低依序為

1. 改寫的設定
2. 內嵌設定
3. 供應商定義的設定

啟用預先定義的變數群組

變數群組是一項功能，可讓分析供應商將一組預先定義的變數分組，以便輕鬆啟用。然後，這些變數將會解析並連同指定的 configRewriter 端點一起傳送。

分析供應商需要在 configRewriter 設定內建立新的 varGroups 物件，以啟用此功能。發布商接著可以將他們希望在其分析設定中啟用的任何已命名的分析供應商建立的 varGroups 納入。所有 AMP HTML 替換指南支援的變數都可以使用。重要注意事項： ${varName} 變體將無法運作。

例如，我們可能有一個供應商的設定看起來像這樣

// This is predefined by vendor.
export const VENDOR_ANALYTICS_CONFIG = {
    ...
    'configRewriter': {
      'url': 'https://www.vendor.com/amp-config-rewriter',
      'varGroups' : {
        'group1': {
          'referrer': 'DOCUMENT_REFERRER',
          'source': 'SOURCE_URL',
        'group2': {
          'title': 'TITLE',
        },
      },
    },
    ...
}

您可以透過在供應商的 <amp-analytics> 設定中，為指定的 varGroups 納入 {enabled: true} 來指定啟用哪些變數群組。enabled 是保留關鍵字，不能用作變數名稱。

在以下範例中，group1 和 group2 都已啟用。任何未明確啟用的群組都將被忽略。然後，執行階段會解析所有這些已啟用的變數，並將它們合併到單一 configRewriter.vars 物件中，該物件將會傳送至設定改寫器網址。

/* Included on publisher page */
<amp-analytics type="myVendor" id="myVendor" data-credentials="include">
  <script type="application/json">
    {
      "configRewriter": {
        "varGroups": {
          "group1": {
            "enabled": true
          },
          "group2": {
            "enabled": true
          }
        }
      }
    }
  </script>
</amp-analytics>

在此範例中，要求主體看起來會像這樣

/* Sent to configuration rewriter server. */
"configRewriter": {
  "vars": {
    "referrer": "https://www.example.com",
    "source": "https://www.amp.dev",
    "title": "Cool Amp Tips"
  }
}

設定資料物件

要求

requests 設定物件指定用於將資料傳輸至分析平台以及要求的分批處理或回報行為的網址。request-name 指定應針對特定事件 (例如，pageview、event 等) 傳送哪些要求。request-value 包含 https 網址，該值可能包含可參照其他要求或變數的預留位置符記。request-value 也可以是包含選用要求設定的物件。

使用物件定義要求的屬性為

• baseUrl：定義要求的網址 (必要)。
• reportWindow：選用屬性，用於指定停止回報要求的時間 (以秒為單位)。具有 important: true 的觸發器會覆寫最大回報時間範圍限制。
• origin：選用屬性，用於指定要求的來源

在此範例中，所有要求都有效。

"requests": {
  "base": "https://example.com/analytics?a=${account}&u=${canonicalUrl}&t=${title}",
  "pageview": {
    "baseUrl": "${base}&type=pageview"
  },
  "event": {
    "baseUrl": "${base}&type=event&eventId=${eventId}",
    "batchInterval": 5,
    "reportWindow" : 30
  }
}

某些分析供應商已提供設定，您可以透過 type 屬性使用這些設定。如果您使用的是分析供應商，則可能不需要納入要求資訊。請參閱您的供應商文件，以瞭解是否需要設定要求以及如何設定。

定義要求來源

最上層的 requestOrigin 屬性接受絕對網址，並定義要求的來源。如果宣告了 requestOrigin，則會從該值中擷取來源，並將其前置於 baseUrl。requestOrigin 接受並支援變數替換。變數不會在 requestOrigin 中編碼。

"requestOrigin": "${example}/ignore_query",
"requests": {
  "base": "/analytics?a=${account}",
  "pageview": {
    "baseUrl": "${base}&type=pageview"
  },
  "event": {
    "baseUrl": "${base}&type=event",
  }
},
"vars": {
  "example": "https://example.com"
}

在此範例中，傳出的要求將是 https://example.com/analytics?a=${account}&type=pageview (適用於 pageview 要求) 和 https://example.com/analytics?a=${account}&type=event (適用於 event 要求)。請注意，requestOrigin 值未編碼，且只有來源新增至 baseUrl。

要求物件也可以具有 origin 屬性，該屬性將覆寫此最上層的 requestOrigin 屬性。

"requestOrigin": "https://example.com",
"requests": {
  "pageview": {
    "origin": "https://newexample.com",
    "baseUrl": "/analytics?type=pageview"
  }
}

在此範例中，傳出的要求將是 https://newexample.com/analytics?type=pageview (適用於 pageview 要求)。

排程批次要求

為了減少要求 Ping 的數量，您可以在要求設定中指定分批處理行為。來自使用相同要求的 triggers 的任何 extraUrlParams 都會附加到要求的 baseUrl。

分批處理屬性為 batchInterval。此屬性指定在分批處理佇列中刷新要求 Ping 的時間間隔 (以秒為單位)。batchInterval 可以是數字或數字陣列 (最小時間間隔為 200 毫秒)。要求將遵循陣列中的每個值，然後在到達陣列結尾時重複最後一個間隔值 (或單一值)。

例如，以下設定每 2 秒傳送一個要求 Ping，其中一個範例要求 Ping 看起來像 https://example.com/analytics?rc=1&rc=2。

"requests": {
  "timer": {
    "baseUrl": "https://example.com/analytics?",
    "batchInterval": 2
  }
}
"triggers": {
  "timer": {
    "on": "timer",
    "request" : "timer",
    "timerSpec": {
      "interval": 1
    },
    "extraUrlParams": {
      "rc": "${requestCount}"
    }
  }
}

以下設定在 1 秒後傳送第一個要求 Ping，然後每 3 秒傳送一個要求。第一個要求 Ping 看起來像 https://example.com/analytics?rc=1，第二個要求 Ping 看起來像 https://example.com/analytics?rc=2&rc=3&rc=4。

"requests": {
  "timer": {
    "baseUrl": "https://example.com/analytics?",
    "batchInterval": [1, 3]
  }
}
"triggers": {
  "timer": {
    "on": "timer",
    "request" : "timer",
    "timerSpec": {
      "interval": 1
    },
    "extraUrlParams": {
      "rc": "${requestCount}"
    }
  }
}

變數

amp-analytics 元件定義了許多可以在要求中使用的基本變數。amp-analytics 變數指南中提供了所有此類變數的清單。此外，AMP HTML 替換指南支援的所有變數也受到支援。

變數會非同步解析，並且可能會延遲要求，直到它們完成為止。例如，頁面隱藏後會計算某些指標，例如累計版面配置位移和最大內容繪製。對於首次輸入延遲，它會在使用者與頁面互動後解析。因此，這些指標可能不適合與所有觸發器一起使用 (例如，在計時器或可見時)。

vars 設定物件可用於定義新的鍵/值組或覆寫可以在 request 值中參照的現有變數。新的變數通常用於指定發布商特定資訊。陣列可用於指定應個別進行網址編碼的數值清單，同時保留逗號分隔符號。支援在陣列中替換內建和自訂變數，但變數展開為另一個陣列時除外。

"vars": {
  "account": "ABC123",
  "countryCode": "tr",
  "tags": ["Swift,Jonathan", "Gulliver's Travels", "${account}"]
}

註冊事件觸發器

triggers 設定物件描述何時應傳送分析要求。triggers 屬性包含觸發器名稱和觸發器設定的鍵/值組。觸發器名稱可以是任何由英數字元 (a-zA-Z0-9) 組成的字串。來自優先順序較低之設定的觸發器會被來自優先順序較高之設定的相同名稱觸發器覆寫。

如需瞭解如何設定觸發器的詳細資訊，請參閱可用的觸發器。

例如，以下設定可用於根據隨機輸入取樣 50% 的要求，或根據用戶端 ID 取樣 1% 的要求。

"triggers": {
  "sampledOnRandom": {
    "on": "visible",
    "request": "request",
    "sampleSpec": {
      "sampleOn": "${random}",
      "threshold": 50
    }
  },
  "sampledOnClientId": {
    "on": "visible",
    "request": "request",
    "sampleSpec": {
      "sampleOn": "${clientId(cookieName)}",
      "threshold": 1
    }
  }
}

元素選取器

某些觸發器 (例如 click、video 和 visible) 允許使用選取器屬性指定單一元素或元素集合。不同的觸發器可以對選取的元素套用不同的限制和解讀，例如選取器是否適用於所有相符的元素或第一個元素，或可以比對哪些元素：所有元素或僅限 AMP 元素。如需更多詳細資訊，請參閱每個相關觸發器的文件。

選取器屬性為

• selector 此屬性用於使用 CSS/DOM 查詢尋找元素或元素集合。可以使用 selectionMethod 變更元素比對方式的語意。此屬性的值可以是下列其中之一

  • 有效的 CSS 選取器，例如 #ad1 或 amp-ad。
  • :root - 一種特殊的選取器，可比對文件根目錄。

• selectionMethod 指定時，此屬性可以具有兩個值之一：scope 或 closest。scope 允許在 amp-analytics 標記的父元素內選取元素。closest 搜尋滿足給定選取器的 amp-analytics 標記的最接近祖先。預設值為 scope。

選取器值

如上所述，對於 click、video 和 visible 觸發器，可以為選取器值指定單一 CSS 選取器或 CSS 選取器集合。

如果指定了單一字串 CSS 選取器，則會擷取對應於該選取器的元素 - 即使 CSS 選取器對應於多個元素也是如此。

在單一設定適用於多個元素的情況下，可以透過一次指定所有選取器來簡化，而不是為每個元素建立個別設定。若要執行此操作，請指定以逗號分隔且個別以引號括住的選取器陣列。

"triggers": {
  "video-pause": {
    "on": "video-pause",
    "request": "event",
    "selector": ["#Video-1", "#Video-2"]
  },
}

可用的觸發器

on 觸發器提供要監聽的事件。有效值為 render-start、ini-load、blur、change、click、scroll、timer、visible、hidden、user-error、access-* 和 video-*。

其他可用的觸發器包括 request、vars、important、selector、selectionMethod、scrollSpec、timerSpec、sampleSpec 和 videoSpec。

"on": "render-start" 觸發器

在 iframe 中嵌入其他文件的 AMP 元素 (例如，廣告) 可能會回報轉譯開始事件 ("on": "render-start")。此事件通常會在可以確認嵌入文件的轉譯已開始時立即發出。請參閱特定 AMP 元素的文件，以瞭解它是否發出此事件。

嵌入元素的觸發器必須包含指向嵌入元素的 selector

"triggers": {
  "renderStart": {
    "on": "render-start",
    "request": "request",
    "selector": "#embed1"
  }
}

文件本身也會發出轉譯開始事件，並且可以設定為

"triggers": {
  "renderStart": {
    "on": "render-start",
    "request": "request"
  }
}

"on": "ini-load" 觸發器

當 AMP 元素或 AMP 文件的初始內容已載入時，會觸發初始載入事件 ("on": "ini-load")。

「初始載入」是根據容器及其初始大小定義的。更具體地說

• 對於文件：第一個可視範圍中的所有元素。
• 對於嵌入元素：嵌入文件中位於嵌入元素初始大小內的所有內容元素。
• 對於簡單的 AMP 元素 (例如 amp-img)：資源本身，例如影像或影片。

嵌入或 AMP 元素的觸發器必須包含指向元素的 selector

"triggers": {
  "iniLoad": {
    "on": "ini-load",
    "request": "request",
    "selector": "#embed1"
  }
}

文件本身也會發出初始載入事件，並且可以設定為

"triggers": {
  "iniLoad": {
    "on": "ini-load",
    "request": "request"
  }
}

"on": "blur" 觸發器

on blur 是瀏覽器事件追蹤器支援的瀏覽器事件的一部分。當指定的元素不再處於焦點時，請使用 blur 觸發器 ("on": "blur") 來觸發要求。使用 selector 來控制哪些元素將導致觸發此要求。觸發器將針對指定選取器比對的所有元素觸發。選取器可以是單一 CSS 查詢選取器或選取器陣列。

"triggers": {
  "inputFieldBlurred": {
    "on": "blur",
    "request": "event",
    "selector": ["inputField-A", "inputField-B"]
    "vars": {
      "eventId": "${id}"
    }
  }
}

"on": "change" 觸發器

與 blur 觸發器類似，change 觸發器是瀏覽器事件的一部分。當指定的元素經歷狀態變更時，請使用 change 觸發器 ("on": "change") 來觸發要求。狀態變更可能因元素而異。使用 selector 來控制哪些元素將導致觸發此要求。選取器可以是單一 CSS 查詢選取器或選取器陣列。觸發器將針對指定選取器比對的所有元素觸發。

"triggers": {
  "selectChange": {
    "on": "change",
    "request": "event",
    "selector":["dropdownA", "dropdownB"],
    "vars": {
      "eventId": "${id}"
    }
  }
}

"on": "click" 觸發器

當點擊指定的元素時，請使用 click 觸發器 ("on": "click") 來觸發要求。使用 selector 來控制哪些元素將導致觸發此要求。觸發器將針對指定選取器比對的所有元素觸發。

"vars": {
  "id1": "#socialButtonId",
  "id2": ".shareButtonClass"
},
"triggers": {
  "anchorClicks": {
    "on": "click",
    "selector": "a, ${id1}, ${id2}",
    "request": "event",
    "vars": {
      "eventId": 128
    }
  }
}

除了作為觸發器一部分提供的變數外，您還可以為 作為資料屬性的變數指定額外項目/覆寫。如果使用，這些資料屬性必須是指定為 selector 的元素的一部分。

"on": "scroll" 觸發器

當頁面捲動時，在特定條件下使用 scroll 觸發器 ("on": "scroll") 來觸發要求。此觸發器提供 特殊變數，指示觸發傳送要求的界限。使用 scrollSpec 來控制何時觸發此事件。

scrollSpec 是一個物件，其中包含屬性

• horizontalBoundaries、verticalBoundaries (捲動事件觸發時，至少需要其中一個)。

  這些應該是包含觸發捲動事件的百分比界限的數字陣列。

  (為了保持頁面效能，這些百分比會四捨五入到 5 的倍數。)

• useInitialPageSize (選用，預設為 false)

  如果設定為 true，則會根據頁面的初始大小計算捲動位置，而忽略調整大小後的新尺寸。

例如，在以下程式碼片段中，當頁面垂直捲動 25%、50% 和 90% 時，將會觸發捲動事件。此外，當頁面水平捲動到捲動寬度的 90% 時，也會觸發該事件。

"triggers": {
  "scrollPings": {
    "on": "scroll",
    "scrollSpec": {
      "verticalBoundaries": [25, 50, 90],
      "horizontalBoundaries": [90]
    },
    "request": "event"
  }
}

"on": "timer" 觸發器

使用 timer 觸發器 ("on": "timer") 以固定的時間間隔觸發要求。使用 timerSpec 來控制何時觸發此事件。

timerSpec 類型為 timer 的觸發器規格。除非指定了 startSpec，否則計時器將立即觸發 (預設情況下，可以取消設定)，然後以指定的間隔觸發。

• interval 計時器間隔的長度 (以秒為單位)。
• maxTimerLength 計時器將觸發的最長持續時間 (以秒為單位)。當達到 maxTimerLength 時，將會觸發額外要求。預設值為 2 小時。當存在 stopSpec，但未指定 maxTimerLength 時，預設值將為無限。
• immediate 立即觸發計時器或不觸發。布林值，預設為 true

請參閱以下範例

"triggers": {
  "pageTimer": {
    "on": "timer",
    "timerSpec": {
      "interval": 10,
      "maxTimerLength": 600
    },
    "request": "pagetime"
  }
}

若要設定為使用者事件計時的計時器，請使用

• startSpec 觸發計時器何時開始的規格。使用 on 和 selector 的值來追蹤特定事件。具有 startSpec 但沒有 stopSpec 的設定只會在達到 maxTimerLength 後停止。
• stopSpec 觸發計時器何時停止的規格。具有 stopSpec 但沒有 startSpec 的設定將立即開始，但僅在指定的事件時停止。

請參閱關於觸發器的規格，以瞭解建立巢狀計時器觸發器的詳細資訊。請注意，不允許使用計時器觸發器來啟動或停止計時器。以下範例示範如何根據文件的 hidden 和 visible 事件，以及根據影片的 play 和 pause 事件設定觸發器。

"triggers": {
  "startOnVisibleStopOnHiddenTimer": {
    "on": "timer",
    "timerSpec": {
      "interval": 5,
      "startSpec": {
        "on": "visible",
        "selector": ":root"
      },
      "stopSpec": {
        "on": "hidden",
        "selector": ":root"
      }
    },
    "request": "timerRequest"
  },
  "videoPlayTimer": {
    "on": "timer",
    "timerSpec": {
      "interval": 5,
      "startSpec": {
        "on": "video-play",
        "selector": "amp-video"
      },
      "stopSpec": {
        "on": "video-pause",
        "selector": "amp-video"
      }
    },
    "request": "videoRequest"
  }
}

"on": "visible" 觸發器

當頁面變成可見時，請使用頁面可見性觸發器 ("on": "visible") 來觸發要求。可以使用 visibilitySpec 設定此觸發器的觸發。

"triggers": {
  "defaultPageview": {
    "on": "visible",
    "request": "pageview"
  }
}

可以使用 selector 為任何 AMP 或非 AMP 元素或文件根目錄設定元素可見性觸發器。當指定的元素符合可以使用 visibilitySpec 自訂的可見性參數時，將會觸發觸發器。

"triggers": {
  "defaultPageview": {
    "on": "visible",
    "request": "elementview",
    "selector": "#ad1",
    "visibilitySpec": {/* optional visibility spec */}
  }
}

元素可見性觸發器會等待 visibilitySpec 中 waitFor 屬性指定的訊號，然後再追蹤元素可見性。如果未指定 waitFor，它會等待元素的 ini-load 訊號。如需更多詳細資訊，請參閱 waitFor 文件。如果指定了 reportWhen，則觸發器會在傳送事件之前等待該訊號。這在例如於頁面關閉時傳送分析事件時很有用。

selector 可以是單一選取器字串 (如上所示) 或選取器字串陣列 (如下所示)。如果 selector 是字串，則它將僅用於指定單一元素或文件根目錄。如果 selector 是字串陣列，則每個選取器將指定文件中共用該選取器且具有 data-vars-* 屬性的所有元素 (適用於識別元素)。

"triggers": {
  "defaultPageview": {
    "on": "visible",
    "request": "adViewWithId",
    "selector": ["amp-ad", "#myImg.red"],
    "visibilitySpec": {/* optional visibility spec */}
  }
}

"on": "hidden" 觸發器

當頁面變成隱藏時，請使用 hidden 觸發器 ("on": "hidden") 來觸發要求。

"triggers": {
  "defaultPageview": {
    "on": "hidden",
    "request": "pagehide"
  }
}

可以納入 visibilitySpec，以便僅在滿足可見性持續時間條件時才觸發要求。

"triggers": {
  "defaultPageview": {
    "on": "hidden",
    "request": "pagehide",
    "visibilitySpec": {
      "selector": "#anim-id",
      "visiblePercentageMin": 20,
      "totalTimeMin": 3000
    }
  }
}

以上設定轉換為

當頁面變成隱藏時，如果元素 #anim-id 已可見 (可視範圍中超過 20% 的區域) 總共超過 3 秒，則觸發要求。

"on": "user-error" 觸發器

當發生可歸因於頁面作者或頁面發布中所用軟體的錯誤時，會觸發使用者錯誤事件 ("on": "user-error")。這包括但不限於 AMP 元件設定錯誤、廣告設定錯誤或判斷提示失敗。使用者錯誤也會在開發人員主控台中回報。

"triggers": {
  "userError": {
    "on": "user-error",
    "request": "error"
  }
}

"on": 元件專用觸發器

• 存取觸發器：AMP 存取系統會針對存取流程中的不同狀態發出許多事件。如需存取觸發器 ("on": "access-*") 的詳細資訊，請參閱 AMP 存取與分析。
• 影片分析觸發器：影片分析提供數個觸發器 ("on": "video-*")，發布商可以使用這些觸發器來追蹤影片生命週期中發生的不同事件。更多詳細資訊請參閱 AMP 影片分析。
• 瀏覽器事件追蹤器：AMP 提供追蹤自訂瀏覽器事件集的功能。允許清單中列出了支援的瀏覽器事件集。目前，支援事件 ("on": "change") 和 ("on": "blur")。

request 觸發器

要傳送的要求名稱 (如 requests 章節中所指定)。

vars 觸發器 (選用)

包含鍵值組的物件，用於覆寫在頂層配置中定義的 vars，或指定此觸發器獨有的 vars。

important 觸發器 (選填)

可以指定與支援批次處理行為或回報視窗的請求一起使用。將 important 設定為 true 可以幫助刷新某些特定觸發器的批次請求佇列。在這種情況下，有可能在不遺失重要觸發事件的情況下減少請求 ping 的數量。將 important 設定為 true 也可以覆寫請求的 reportWindow 值，以發送重要的請求 ping。

selector 和 selectionMethod 觸發器 (選填)

可以為某些觸發器指定，例如 click 和 visible。詳情請參閱 元素選擇器。

scrollSpec 觸發器

此配置與 scroll 觸發器結合使用。詳情請參閱 scroll。當 on 設定為 scroll 時為必填。

timerSpec 觸發器

此配置與 timer 觸發器結合使用。詳情請參閱 timer。當 on 設定為 timer 時為必填。

sampleSpec 觸發器 (選填)

此物件用於定義請求在發送之前如何取樣。此設定允許基於隨機輸入或其他平台支援的 vars 進行取樣。該物件包含配置，用於指定用於產生雜湊值的輸入和雜湊值必須滿足的閾值。

• sampleOn：此字串範本會透過填入平台變數來擴展，然後進行雜湊處理以產生一個數字，用於以下 threshold 中描述的取樣邏輯。
• threshold：此配置用於過濾掉不符合特定條件的請求。為了使請求能夠傳送到分析供應商，以下邏輯應為真 HASH(sampleOn) < threshold。

videoSpec 觸發器

此配置與 video-* 觸發器結合使用。當 on 設定為 video-* 時使用。

傳輸

transport 配置物件指定如何發送請求。此值是一個物件，其中包含指示哪些傳輸方法可接受的欄位。

• beacon 表示可以使用 navigator.sendBeacon 來傳輸請求。這將發送一個帶有憑證的 POST 請求。除非 useBody 為 true，否則請求將以空主體發送。有關 useBody 的更多資訊，請參閱 額外 URL 參數。
• xhrpost 表示可以使用 XMLHttpRequest 來傳輸請求。這將發送一個帶有憑證的 POST 請求。除非 useBody 為 true，否則請求將以空主體發送。有關 useBody 的更多資訊，請參閱 額外 URL 參數。
• image 表示可以透過產生 Image 標籤來發送請求。這將發送一個 GET 請求。若要抑制因空回應或請求失敗而產生的主控台警告，請設定 "image": {"suppressWarnings": true}。
• iframe 表示可以使用 iframe 來傳輸請求。詳情請參閱 iframe。

如果啟用多個上述傳輸方法，則優先順序為 iframe > beacon > xhrpost > image。只會使用一種傳輸方法，而且它將是允許且可用的最高優先順序方法。如果用戶端的使用者代理程式不支援某種方法，則將使用下一個最高優先順序的已啟用方法。預設情況下，以上四種方法都已啟用。

在以下範例中，未指定 iframe URL，並且 beacon 和 xhrpost 設定為 false，因此即使它們的優先順序高於 image，也不會使用它們。image 預設會設定為 true，但在此處明確宣告。如果用戶端的使用者代理程式支援 image 方法，則將使用它；否則，將不會發送任何請求。

"transport": {
  "beacon": false,
  "xhrpost": false,
  "image": true
}

若要了解更多資訊，請參閱 這個實作 iframe 傳輸用戶端 API 的範例 和 這個整合該 iframe 的範例頁面。該範例載入了一個 虛擬廣告，其中包含 amp-analytics 標籤。請注意，虛擬廣告內容包含一些必須遵循的額外配置指示。

iframe

經 MRC 認證的供應商可以透過將 URL 字串新增至 iframe-transport-vendors.js，來使用第四種傳輸機制「iframe 傳輸」。這表示應建立一個 iframe，其 src 屬性設定為此 URL，並且請求將透過 window.postMessage() 發送到該 iframe。在這種情況下，請求不必是完整的 URL。iframe 只能在 iframe-transport-vendors.js 中指定，而不能在 amp-analytics 標籤內內嵌指定，也不能透過遠端配置指定。此外，供應商框架可能會發送回應，供 amp-ad-exit 使用。請參閱 analytics-iframe-transport-remote-frame.html 和 fake_amp_ad_with_iframe_transport.html：前者檔案發送 {'collected-data': 'abc'} 的回應 JSON 物件，而後者檔案使用該物件將 finalUrl 中的 'bar_' 替換為 'abc'。

參照網址政策

參照網址政策可以指定為 transport 配置中的 referrerPolicy 欄位。目前僅支援 no-referrer。參照網址政策僅適用於 image 傳輸。如果指定 referrerPolicy: no-referrer，則 beacon 和 xhrpost 傳輸將被覆寫為 false。

"transport": {
  "beacon": false,
  "xhrpost": false,
  "image": true,
  "referrerPolicy": "no-referrer"
}

額外 URL 參數

extraUrlParams 配置物件指定要包含在請求中的額外參數。預設情況下，額外 URL 參數會透過常用的 "&foo=baz" 慣例附加到請求 URL 的查詢字串。

這是一個範例，它會將 &a=1&b=2&c=3 附加到請求

"extraUrlParams": {
  "a": "1",
  "b": "2",
  "c": "3"
}

如果啟用 useBody 並且請求是透過 beacon 或 xhrpost 傳輸方法發送的，則 extraUrlParams 可以透過請求主體而不是 URL 發送。在這種情況下，參數不會進行 URL 編碼或扁平化處理。

useBody 配置選項指示是否將 extraUrlParams 包含在 POST 請求主體中，而不是像 URL 編碼的查詢參數一樣包含在 URL 中。

useBody 僅適用於 beacon 和 xhrpost 傳輸方法。如果 useBody 為 true 且與其中一種傳輸方法結合使用，則 extraUrlParams 會在 POST 請求主體中發送。否則，請求將以空主體發送，並且 extraUrlParams 會包含為 URL 參數。

使用 useBody，您可以在 extraUrlParams 中包含巢狀物件。但是，如果請求回退到其他不支援 useBody 的傳輸選項（例如 image），則這些巢狀物件將字串化為 URL，顯示為 [object Object]。

"transport": {
  "beacon": true,
  "xhrpost": true,
  "useBody": true,
  "image": false
}

對應參數中的替換字串

extraUrlParamsReplaceMap 屬性指定鍵和值的對應，這些鍵和值充當 String.replace() 的參數，用於預先處理 extraUrlParams 配置中的鍵。例如，如果 extraUrlParams 配置定義了 "page.title": "The title of my page"，並且 extraUrlParamsReplaceMap 定義了 "page.": "_p_"，則 &_p_title=The%20title%20of%20my%20page%20 將會附加到請求。

使用 extraUrlParams 不需要 extraUrlParamsReplaceMap。如果未定義 extraUrlParamsReplaceMap，則不會發生字串替換，並且 extraUrlParams 中定義的字串將按原樣使用。

如果啟用 useBody 並且請求是透過 beacon 或 xhrpost 傳輸方法發送的，則 extraUrlParamsReplaceMap 字串替換將僅對 extraUrlParams 中的頂層鍵執行。

使用 visibilitySpec 自訂 visible 和 hidden 觸發器

visibilitySpec 是一組條件和屬性，可以應用於 visible 或 hidden 觸發器，以變更它們觸發的時間。如果指定了多個屬性，則它們都必須為 true，請求才能觸發。visibilitySpec 中支援的配置屬性包括

• waitFor：此屬性指示可見性觸發器應等待特定訊號，然後再追蹤可見性。支援的值包括 none、ini-load 和 render-start。如果未定義 waitFor，則在指定選擇器時，預設值為 ini-load（對於 AMP 元素），否則為 none。追蹤非 AMP 元素時，僅支援 none，這是其預設值。追蹤非 AMP 元素可能不總是按預期工作。例如，追蹤包含 <amp-iframe> 的 <div> 元素，可能無法準確地等待 iframe 加載完成，然後再發送訊號。

• reportWhen：此屬性指示可見性觸發器應等待特定訊號，然後再發送觸發器。唯一支援的值是 documentExit。reportWhen 和 repeat 不能在同一個 visibilitySpec 中同時使用。請注意，當指定 reportWhen 時，即使在訊號發送時未滿足或先前未滿足可見性要求，報告也將在訊號發送時發送。任何相關變數（totalVisibleTime 等）都將根據此 visibilitySpec 中的可見性要求填入。

• continuousTimeMin 和 continuousTimeMax：這些屬性指示當（元素的任何部分）在視口中持續一段時間（介於指定的最小和最大時間之間）時，應觸發請求。時間以毫秒為單位表示。未指定 continuousTimeMin 時，預設值為 0。

• totalTimeMin 和 totalTimeMax：這些屬性指示當（元素的任何部分）在視口中總共一段時間（介於指定的最小和最大時間之間）時，應觸發請求。時間以毫秒為單位表示。未指定 totalTimeMin 時，預設值為 0。

• visiblePercentageMin 和 visiblePercentageMax：這些屬性指示當元素在視口中可見的比例介於指定的最小和最大百分比之間時，應觸發請求。百分比值介於 0 到 100 之間有效。請注意，上限 (visiblePercentageMax) 是包含性的。下限 (visiblePercentageMin) 是排除性的，除非兩個邊界都設定為 0 或都設定為 100。如果兩個邊界都設定為 0，則當元素不可見時觸發觸發器。如果兩個邊界都設定為 100，則當元素完全可見時觸發觸發器。當這些屬性與其他時間相關屬性一起定義時，僅計算滿足這些屬性的時間。visiblePercentageMin 和 visiblePercentageMax 的預設值分別為 0 和 100。

• repeat：如果此屬性設定為 true，則每次滿足 visibilitySpec 條件時，觸發器都會觸發。在以下範例中，如果元素滾動到視圖中的 51%，然後是 49%，然後再次是 51%，則觸發器會觸發兩次。但是，如果 repeat 為 false，則觸發器會觸發一次。repeat 的預設值為 false。reportWhen 和 repeat 不能在同一個 visibilitySpec 中同時使用。

"visibilitySpec": {
  "visiblePercentageMin": 50,
  "repeat": true
}

visiblePercentageThresholds 可以用作建立多個 visibilitySpec 實例的簡寫，這些實例僅在 visiblePercentageMin 和 visiblePercentageMax 上有所不同。例如，以下是等效的

// Two triggers with visibilitySpecs that only differ in visiblePercentageMin and visiblePercentageMax:
"triggers": {
  "pageView_30_to_40": {
    "on": "visible",
    "request": "pageview",
    "selector": "#ad1",
    "visibilitySpec": {
      "visiblePercentageMin": 30,
      "visiblePercentageMax": 40,
      "continuousTimeMin": 1000
    }
  },
  "pageView_40_to_50": {
    "on": "visible",
    "request": "pageview",
    "selector": "#ad1",
    "visibilitySpec": {
      "visiblePercentageMin": 40,
      "visiblePercentageMax": 50,
      "continuousTimeMin": 1000
    }
  }
}

// A single trigger equivalent to both of the above:
"triggers": {
  "pageView": {
    "on": "visible",
    "request": "pageview",
    "selector": "#ad1",
    "visibilitySpec": {
      "visiblePercentageThresholds": [[30, 40], [40, 50]],
      "continuousTimeMin": 1000
    }
  }
}

除了上述條件之外，visibilitySpec 還啟用某些變數，這些變數記錄在 此處。

"triggers": {
  "defaultPageview": {
    "on": "visible",
    "request": "pageview",
    "selector": "#ad1",
    "visibilitySpec": {
      "waitFor": "ini-load",
      "reportWhen": "documentExit",
      "visiblePercentageMin": 20,
      "totalTimeMin": 500,
      "continuousTimeMin": 200
    }
  }
}

除了作為觸發器一部分提供的變數之外，您還可以為 作為資料屬性的變數 指定額外的/覆寫。如果使用，這些資料屬性必須是指定為 selector 的元素的一部分。

連結器

linkers 功能用於啟用跨網域 ID 同步。amp-analytics 將使用 配置物件 來建立「連結器字串」，該字串將作為 URL 參數附加到頁面上指定的輸出連結。當使用者點擊其中一個連結時，目標頁面將從 URL 參數中讀取連結器字串以執行 ID 同步。這通常用於在 AMP 代理網域和發布商網域之間加入使用者會話。

有關設定連結器配置的詳細資訊，請參閱 連結器 ID 轉發。

如果您需要接收此參數，有關如何建立此參數的資訊，請參閱 連結器 ID 接收。

Cookie

cookies 功能支援透過從文件 URL 中提取 QUERY_PARAM 和 LINKER_PARAM 資訊，將 Cookie 寫入來源網域。它可以與 linkers 功能一起使用，以執行從 AMP 代理網域到發布商網域上的 AMP 頁面的 ID 同步。

有關設定 cookies 配置的詳細資訊，請參閱 在 AMP 頁面上接收連結器參數。

屬性

type (類型)

指定供應商的類型。有關詳細資訊，請參閱 分析供應商 清單。

<amp-analytics
  type="googleanalytics"
  config="https://example.com/analytics.account.config.json"
></amp-analytics>

config (選填)

這是一個選填屬性，可用於從指定的遠端 URL 載入配置。指定的 URL 應使用 HTTPS 協定。另請參閱下方的 data-include-credentials 屬性。URL 可能包含 AMP URL 變數。回應必須遵循 AMP CORS 安全指南。

<amp-analytics
  config="https://example.com/analytics.config.json"
></amp-analytics>

data-credentials (選填)

如果設定為 include，則啟用在透過 config 屬性指定的請求上讀取和寫入 Cookie 的能力。這是一個選填屬性。

data-consent-notification-id (選填)

如果提供，則頁面將不會處理分析請求，直到使用者確認（接受）具有給定 HTML 元素 ID 的 amp-user-notification 為止。這是一個選填屬性。

分析

AMP 元件開發人員可以使用 AMP 分析實作資料收集。有關更多資訊，請參閱 為 AMP 元件實作分析。

Google Analytics 4 和 AMP

有關如何使用 amp-analytics 設定 Google Analytics 4 的資訊，請參閱 amp-analytics 開發人員指南 和 gtagjs 指南

驗證

請參閱 AMP 驗證器規範中的 amp-analytics 規則。