amp-analytics

描述

从 AMP 文档捕获分析数据。

必需脚本

<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) 将合并在一起，使得

远程配置优先于内联配置，并且
内联配置优先于供应商配置。

在开始在您的网站上使用 AMP 分析之前，您需要决定是使用第三方分析工具来分析用户互动，还是使用您自己的内部解决方案。

在配置分析指南中了解有关 AMP 分析的所有信息。

将数据发送到分析供应商

amp-analytics 组件专门设计用于一次度量并报告给多个。如果您已经与一个或多个分析供应商合作，请查看分析供应商列表，查看他们是否已将其解决方案与 AMP 集成。

集成分析供应商

对于集成的 AMP 分析供应商

在 <amp-analytics> 标签中，添加 type 属性，并将其值设置为指定的供应商。
确定要捕获和跟踪的数据，并在配置数据中指定这些详细信息。有关如何捕获分析数据的说明，请参阅供应商的文档。

在以下示例中，分析数据将发送给 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。

如果您的内部解决方案涉及与尚未与 AMP 集成的分析供应商合作，请与供应商合作以确定所需的配置信息。

要将数据发送到特定 URL

确定要捕获和跟踪的数据，并在配置数据中指定这些详细信息。
在requests配置对象中，指定要跟踪的请求类型（例如，页面浏览量、特定的触发事件）以及要将跟踪数据发送到的 URL。

在处理分析请求的 referrer 标头中的 AMP URL 时，请删除或忽略 usqp 参数。Google 使用此参数来触发 Google AMP 缓存的实验。

下面的示例跟踪页面浏览量。每次页面可见时，触发事件都会触发，并将页面浏览量数据与随机 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 合并所有提供的配置，以确定最终配置，优先级从高到低：

重写配置
内联配置
供应商定义的配置

启用预定义变量组

变量组是一项功能，允许分析提供商将一组预定义的变量分组，以便轻松启用。然后，将解析这些变量并将其发送到指定的 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"
}

在此示例中，对于 pageview 请求，发出的请求将是 https://example.com/analytics?a=${account}&type=pageview，对于 event 请求，发出的请求将是 https://example.com/analytics?a=${account}&type=event。请注意，requestOrigin 值没有被编码，并且只有来源被添加到 baseUrl 中。

请求对象也可以具有 origin 属性，该属性将覆盖此顶层的 requestOrigin 属性。

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

在此示例中，对于 pageview 请求，发出的请求将是 https://newexample.com/analytics?type=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，则滚动位置将根据页面的初始大小计算，忽略调整大小时的新尺寸。

将 <amp-analytics> 与无限滚动体验（例如 <amp-next-page> 和 <amp-list>）一起使用时，您可能会发现使用 useInitialPageSize 以便滚动触发器报告页面的初始高度（在添加 <amp-next-page> 或 <amp-list> 元素之前）很有帮助。请注意，这也会忽略由其他扩展（例如展开的嵌入式内容）引起的大小变化，因此某些滚动事件可能会提前触发。

例如，在以下代码段中，当页面垂直滚动 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。

定时器触发器将继续发送请求，无论文档状态（不活动或隐藏），直到达到 maxTimerLength（如果不存在 stopSpec，则默认为 2 小时，如果存在则为无限）或满足 stopSpec。如果不存在 stopSpec，则 maxTimerLength 将默认为无限。

请参见以下示例

"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 在总共超过 3 秒的时间内可见（视口中超过 20% 的区域），则触发请求。

`"on": "user-error"` 触发器

当发生可归因于页面作者或用于发布页面的软件的错误时，将触发用户错误事件（"on": "user-error"）。这包括但不限于 AMP 组件的错误配置、广告配置错误或断言失败。用户错误也会在开发者控制台中报告。

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

存在一个已知问题，它仍然报告来自 A4A iframe 嵌入的错误，这些错误与页面无关。

`"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 认证的供应商可以通过在 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 对象，后者文件使用该对象将 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 规则。

需要更多帮助吗？

您已经阅读本文档十几次了，但它并没有真正涵盖您所有的问题？也许其他人也有同样的感觉：请在 Stack Overflow 上联系他们。

前往 Stack Overflow

发现错误或缺少功能？

AMP 项目强烈鼓励您的参与和贡献！我们希望您能成为我们开源社区的长期参与者，但也欢迎您为自己特别关注的问题做出一次性贡献。

前往 GitHub

amp-analytics

描述

必需脚本

用法

将数据发送到分析供应商

集成分析供应商

非集成分析供应商

内部发送数据

加载远程配置

动态重写配置

启用预定义变量组

配置数据对象

请求

定义请求来源

安排批量请求

变量

注册事件触发器

元素选择器

选择器值

可用触发器

"on": "render-start" 触发器

"on": "ini-load" 触发器

"on": "blur" 触发器

"on": "change" 触发器

"on": "click" 触发器

"on": "scroll" 触发器

"on": "timer" 触发器

"on": "visible" 触发器

"on": "hidden" 触发器

"on": "user-error" 触发器

"on": 组件特定触发器

request 触发器

vars 触发器（可选）

important 触发器（可选）

selector 和 selectionMethod 触发器（可选）

scrollSpec 触发器

timerSpec 触发器

sampleSpec 触发器（可选）

videoSpec 触发器

传输