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 的数量，您可以在请求配置中指定分批行为。使用相同请求的任何 extraUrlParams 从 triggers 追加到请求的 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 计时器类型触发器的规范。除非指定了 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 Access 系统针对访问流程中的不同状态发出大量事件。有关访问触发器（"on": "access-*"）的详细信息，请参阅 AMP Access 和 Analytics。
• 视频分析触发器：视频分析提供了多个触发器（"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 为真，否则将发送一个空主体请求。有关 useBody 的更多信息，请参阅 其他 URL 参数。
• xhrpost 指示可以使用 XMLHttpRequest 传输请求。这将发送带有凭据的 POST 请求。除非 useBody 为真，否则将发送一个空主体请求。有关 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：前一个文件发送响应 JSON 对象 {'collected-data': 'abc'}，后一个文件使用该对象将 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 将附加到请求中。

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 可用作创建多个仅在 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 还启用某些变量，这些变量记录在 此处。

"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 代理域执行 ID 同步到发布商域上的 AMP 页面。

有关设置 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 规则。