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

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

使用計時器觸發器 ("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" 觸發器

當頁面變為隱藏時，請使用隱藏觸發器 ("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

通過將 URL 字串新增至 iframe-transport-vendors.js，經 MRC 認證的供應商可以利用第四種傳輸機制「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"
}

額外網址參數

extraUrlParams 設定物件指定要包含在請求中的其他參數。預設情況下，額外網址參數會透過常用的 "&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 規則。