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

在以下示例中，分析数据将发送到尼尔森，这是一家已与 AMP 集成的第三方分析提供商。有关配置尼尔森分析数据的详细信息，请参见尼尔森文档。

<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。

在分析请求的引用头中处理 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。任何未明确启用的组都将被忽略。然后，运行时将解析所有这些已启用的变量，并将它们合并到将发送到配置重写器 URL 的单个 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://amp.org.cn",
    "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) 组成的字符串。来自优先级较低的配置的触发器会被来自优先级较高的配置的同名触发器覆盖。

有关如何设置触发器的详细信息，请参阅可用触发器。

例如，以下配置可用于基于随机输入或基于客户端 ID 以 1% 的概率对 50% 的请求进行采样。

"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，则滚动位置将根据页面的初始大小计算，忽略调整大小时的新尺寸。

当在无限滚动体验（例如 <amp-next-page> 和 <amp-list>）中使用 <amp-analytics> 时，您可能会发现使用 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"` 触发器

使用定时器触发器（"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 在视口中可见（超过 20% 的面积）的时间总计超过 3 秒，则触发请求。

`"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 认证的供应商可以通过将 URL 字符串添加到 iframe-transport-vendors.js 来使用第四种传输机制“iframe 传输”。这表示应该创建一个 iframe，其 src 属性设置为此 URL，并且请求将通过 window.postMessage() 发送到该 iframe。在这种情况下，请求不需要是完整的 URL。iframe 只能在 iframe-transport-vendors.js 中指定，而不能在 amp-analytics 标签中内联指定，也不能通过远程配置指定。此外，供应商框架可能会发送响应，以供 amp-ad-exit 使用。请参阅 analytics-iframe-transport-remote-frame.html 和 fake_amp_ad_with_iframe_transport.html：前一个文件发送一个 {'collected-data': 'abc'} 的响应 JSON 对象，后一个文件使用该对象将 finalUrl 中的 'bar_' 替换为 'abc'。

引用策略

可以在 transport 配置中将引荐来源策略指定为 referrerPolicy 字段。目前仅支持 no-referrer。引荐来源策略仅适用于 image 传输。如果指定了 referrerPolicy: no-referrer，则 beacon 和 xhrpost 传输将被覆盖为 false。

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

额外的 URL 参数

extraUrlParams 配置对象指定要包含在请求中的其他参数。默认情况下，额外的 URL 参数通过常用的 "&foo=baz" 约定附加到请求 URL 的查询字符串中。

这是一个将 &a=1&b=2&c=3 附加到请求的示例

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

如果启用了 useBody，并且请求是通过 beacon 或 xhrpost 传输方法发送的，则 extraUrlParams 可以通过请求正文而不是 URL 发送。在这种情况下，参数不会进行 URL 编码或扁平化处理。

useBody 配置选项指示是否将 extraUrlParams 包含在 POST 请求正文中，而不是作为 URL 编码的查询参数包含在 URL 中。

useBody 仅适用于 beacon 和 xhrpost 传输方法。如果 useBody 为 true，并且与这两种传输方法中的任何一种一起使用，则 extraUrlParams 将在 POST 请求正文中发送。否则，请求将以空正文发送，并且 extraUrlParams 将作为 URL 参数包含。

使用 useBody，您可以在 extraUrlParams 中包含嵌套对象。但是，如果请求回退到不支持 useBody 的其他传输选项（例如 image），则这些嵌套对象将作为 [object Object] 字符串化到 URL 中。

"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 可以用作创建多个仅在 visiblePercentageMin 和 visiblePercentageMax 中不同的 visibilitySpec 实例的简写。例如，以下是等效的

// 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 还启用了一些变量，这些变量在此处记录 here。

"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 页面上接收链接器参数。

属性

`类型`

指定供应商的类型。有关详细信息，请参阅分析供应商列表。

<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 触发器

传输