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"
}

在此示例中，对于 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") 在指定的元素不再具有焦点时触发请求。使用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，则滚动位置将基于页面的初始大小计算，忽略调整大小后的新尺寸。

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

通过向 iframe-transport-vendors.js 添加 URL 字符串，经 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 对象，后一个文件使用该对象将 'abc' 替换为 finalUrl 中的 'bar_'。

引用策略

可以在 transport 配置中将 referrer policy 指定为 referrerPolicy 字段。目前仅支持 no-referrer。Referrer policy 仅适用于 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 将附加到请求中。

extraUrlParamsReplaceMap 不是使用 extraUrlParams 所必需的。如果未定义 extraUrlParamsReplaceMap，则不会发生字符串替换，并且 extraUrlParams 中定义的字符串将按原样使用。

如果启用了 useBody 并且请求通过 beacon 或 xhrpost 传输方法发送，则 extraUrlParamsReplaceMap 字符串替换将仅在 extraUrlParams 中的顶级键上执行。

使用 visibilitySpec 自定义 visible 和 hidden 触发器

visibilitySpec 是一组条件和属性，可以应用于 visible 或 hidden 触发器以更改它们的触发时间。如果指定了多个属性，则它们必须全部为真，才能触发请求。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 规则。