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 屬性中指定 URL 來遠端擷取。此外，也可以透過使用 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 中整合您的分析工具。或者，與您的供應商合作，將資料傳送至他們指定的 URL。在下方的內部傳送資料章節中瞭解更多資訊。

內部傳送資料

如果您有自己的內部解決方案來衡量使用者互動，那麼將 AMP 分析與該解決方案整合所需的唯一東西就是 URL。這就是您將傳送資料的地方。您也可以將資料傳送至各種 URL。例如，您可以將網頁瀏覽資料傳送至一個 URL，並將社群互動資料傳送至另一個 URL。

若要將資料傳送至特定 URL

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

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

<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 屬性以及設定資料的 URL。指定的 URL 應使用 HTTPS 協定。URL 可能包含AMP URL 變數。若要存取 Cookie，請參閱data-credentials 屬性。回應必須遵循AMP CORS 安全性指南。

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

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

動態重寫設定

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

分析供應商會指定具有伺服器 URL 的 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 物件中，該物件將傳送至設定重寫器 URL。

/* 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 設定物件指定用於將資料傳輸到分析平台的 URL，以及要求的批次處理或回報行為。request-name 指定應針對特定事件 (例如，pageview、event 等) 傳送哪些要求。request-value 包含 https URL，該值可能包含可參考其他要求或變數的預留位置權杖。request-value 也可以是一個物件，其中包含選用的要求設定。

使用物件定義要求的屬性如下：

• baseUrl：定義要求的 URL (必要)。
• 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 屬性接受絕對 URL，並定義要求的來源。如果宣告了 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 值中參考的現有變數。新變數通常用於指定發佈商特定資訊。陣列可用於指定應個別進行 URL 編碼的數值清單，同時保留逗號分隔符號。支援在陣列中替換內建和自訂變數，但變數展開為另一個陣列時除外。

"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" 觸發器

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

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

• 對於文件：第一個視埠中的所有元素。
• 對於內嵌元素：內嵌文件中位於內嵌元素初始大小內的所有內容元素。
• 對於簡單的 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" 觸發器

使用計時器觸發器 ("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，否則請求將以空白主體發送。如需關於 額外的 URL 參數 的更多資訊，請參閱 useBody。
• 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'。

Referrer policy

可以在 transport 設定中將 Referrer 政策指定為 referrerPolicy 欄位。目前僅支援 no-referrer。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 規則。