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 的更多資訊。
• xhrpost 指示可以使用 XMLHttpRequest 來傳輸要求。這將傳送具有認證的 POST 要求。除非 useBody 為 true，否則將使用空主體傳送要求。請參閱額外的網址參數以瞭解關於 useBody 的更多資訊。
• image 指示可以透過產生 Image 標記來傳送要求。這將傳送 GET 要求。若要隱藏因空回應或要求失敗而導致的主控台警告，請設定 "image": {"suppressWarnings": true}。
• iframe 指示可以使用 iframe 來傳輸要求。請參閱iframe 以瞭解詳細資訊。

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

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

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

若要瞭解詳情，請參閱這個實作 iframe 傳輸用戶端 API 的範例，以及這個整合該 iframe 的範例頁面。此範例載入一個虛擬廣告，其中包含 amp-analytics 標記。請注意，虛擬廣告內容包含一些必須遵循的額外設定指示。

iframe

通過 MRC 認證的供應商可以通過向 iframe-transport-vendors.js 添加 URL 字串來使用第四種傳輸機制「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 物件，後一個檔案使用該物件將 'bar_' 替換為 finalUrl 中的 'abc'。

Referrer policy (參照網址政策)

參照網址政策可以指定為 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 (連結器)

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

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

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

Cookies (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 獲得使用者確認（接受）為止。這是一個可選屬性。

Analytics (分析)

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

Google Analytics 4 和 AMP

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

驗證

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