重要提示：此文档不适用于您当前选择的格式 email！

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。

在处理分析请求的引用标头中的 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://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}"
    }
  }
}

Vars

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") 可在指定元素不再处于焦点时触发请求。使用 selector 来控制哪些元素会触发此请求。此触发器将为指定选择器匹配的所有元素触发。选择器可以是单个 CSS 查询选择器，也可以是选择器数组。

"triggers": {
  "inputFieldBlurred": {
    "on": "blur",
    "request": "event",
    "selector": ["inputField-A", "inputField-B"]
    "vars": {
      "eventId": "${id}"
    }
  }
}

`"on": "change"` 触发器

与“失去焦点”触发器类似，“更改”触发器也是浏览器事件的一部分。使用“更改”触发器 ("on": "change") 可在指定元素发生状态更改时触发请求。不同元素的状态更改可能不同。使用 selector 来控制哪些元素会触发此请求。选择器可以是单个 CSS 查询选择器，也可以是选择器数组。此触发器将为指定选择器匹配的所有元素触发。

"triggers": {
  "selectChange": {
    "on": "change",
    "request": "event",
    "selector":["dropdownA", "dropdownB"],
    "vars": {
      "eventId": "${id}"
    }
  }
}

`"on": "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"` 触发器

使用“滚动”触发器 ("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"` 触发器

使用“定时器”触发器 ("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，而无需考虑 reportWindow 的值。

`selector` 和 `selectionMethod` 触发器（可选）

可以为某些触发器指定，例如 click 和 visible。有关详细信息，请参阅元素选择器。

`scrollSpec` 触发器

此配置与 scroll 触发器结合使用。有关详细信息，请参阅 scroll。当 on 设置为 scroll 时是必需的。

`timerSpec` 触发器

此配置与 timer 触发器结合使用。有关详细信息，请参阅 timer。当 on 设置为 timer 时是必需的。

`sampleSpec` 触发器（可选）

此对象用于定义如何在发送请求之前对其进行采样。此设置允许基于随机输入或其他平台支持的 vars 进行采样。该对象包含配置，以指定用于生成哈希的输入和哈希必须满足的阈值。

sampleOn：此字符串模板通过填充平台变量进行扩展，然后进行哈希处理以生成一个数字，用于以下 threshold 下所述的采样逻辑。
threshold：此配置用于筛选出不满足特定条件的请求。要使请求通过到分析供应商，以下逻辑应为 true：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 传输方法发送的，则可以通过请求主体而不是 URL 发送 extraUrlParams。在这种情况下，参数不会进行 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 接收。

Cookies

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

描述

必需脚本

用法

向分析供应商发送数据

集成的分析供应商

非集成的分析供应商

内部发送数据

加载远程配置

动态重写配置

启用预定义的变量组

配置数据对象

请求

定义请求来源

计划批量请求

Vars

注册事件触发器

元素选择器

选择器值

可用触发器

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

传输