CrUX API

借助 CrUX API,您能够以低延迟方式访问以网页和源站粒度汇总的真实用户体验数据。

常见用例

借助 CrUX API,您可以查询特定 URI 的用户体验指标,例如“获取 https://example.com 源的指标”。

CrUX API 密钥

使用 CrUX API 需要 Google Cloud API 密钥。您可以在凭据页面中创建一个,然后配置该凭据以供 Chrome UX Report API 使用。

在您获得 API 密钥后,您的应用便可将查询参数 key=[YOUR_API_KEY] 附加到所有请求网址中。请参阅下面的查询示例

API 密钥可以安全地嵌入网址中,而无需进行任何编码。

数据模型

本部分详细介绍了请求和响应中的数据结构。

录制

关于网页或网站的离散信息。记录可包含特定于标识符和特定维度组合的数据。一条记录可以包含一个或多个指标的数据。

标识符

标识符指定应查找哪些记录。在 CrUX 中,这些标识符是网页和网站。

原点

如果标识符是某个来源,则该来源中所有网页的所有数据都会汇总在一起。例如,假设 http://www.example.com 源包含以下站点地图中列出的网页:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

这意味着,当查询来源设为 http://www.example.com 的 Chrome 用户体验报告时,系统会返回 http://www.example.com/http://www.example.com/foo.htmlhttp://www.example.com/bar.html 数据并将它们汇总在一起,因为这些都是该来源下的所有网页。

网址

如果标识符是网址,则只会返回该特定网址的数据。我们再来看一下 http://www.example.com 源站点地图:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

如果将标识符设置为网址并将其值设为 http://www.example.com/foo.html,则系统将仅返回该网页的数据。

维度

维度用于识别记录汇总时所参照的特定数据组,例如,PHONE 的外形规格表示记录包含与移动设备上发生的加载有关的信息。每个维度都有一定数量的值,如果没有指定该维度,则意味着该维度将针对所有值进行汇总。例如,如果未指定外形规格,则表示记录包含发生在任何外形规格上的加载的相关信息。

设备规格

最终用户用于导航到相应页面的设备类。这是一个通用的设备类,分为 PHONETABLETDESKTOP

有效连接类型

有效连接类型是指设备在导航至相应网页时估算的连接质量。这是一个常规类,分为 offlineslow-2G2G3G4G

指标

我们会以直方图、百分位数和分数形式报告指标的统计汇总数据。

直方图

当指标以直方图形式表示时,我们会显示属于该指标特定范围的网页加载所占的百分比。

示例指标的简单三分箱直方图如下所示:

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.38179
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.49905
    },
    {
      "start": 3000,
      "density": 0.11916
    }
  ]
}

这些数据表明,对于 38.179% 的网页加载,示例指标的测量时间介于 0 毫秒到 1,000 毫秒之间。此直方图中不包含指标的单位,在本例中,我们假定以毫秒计。

此外,49.905% 的网页加载的指标值介于 1,000 毫秒到 3,000 毫秒之间,有 11.916% 的网页加载时长大于 3,000 毫秒。

百分位

指标还可能包含可用于其他分析的百分位数。我们会按指标的指定百分位报告特定指标值。它们基于全部可用数据,而不是最终的分箱数据,因此不一定与基于最终分箱直方图的插值百分位匹配。

{
  "percentiles": {
    "p75": 2063
  }
}

在本示例中,至少有 75% 的网页加载是使用指标值 <= 2063 衡量的。

分数

分数表示可以以特定方式标记的网页加载所占的百分比。 在本例中,指标值就是这些标签。例如:

"fractions": {
  "desktop": 0.0377,
  "tablet": 0.0288,
  "phone": 0.9335
}

在该示例中,3.77% 的网页加载是在桌面设备、2.88% 的平板电脑上以及 93.35% 的手机上测得的,因此总体上为 100%。

指标值类型

CrUX API 指标名称 数据类型 公制单位 统计汇总 web.dev 文档
cumulative_layout_shift 双精度编码为字符串 无单位 包含三个分箱的直方图,百分位数为 p75 cls
first_contentful_paint int 毫秒 包含三个分箱的直方图,百分位数为 p75 fcp
first_input_delay int 毫秒 包含三个分箱的直方图,百分位数为 p75 Fibit
interaction_to_next_paint int 毫秒 包含三个分箱的直方图,百分位数为 p75 inp
largest_contentful_paint int 毫秒 包含三个分箱的直方图,百分位数为 p75 lcp
experimental_time_to_first_byte int 毫秒 包含三个分箱的直方图,百分位数为 p75 Ttfb

BigQuery 指标名称映射

CrUX API 指标名称 BigQuery 指标名称
cumulative_layout_shift layout_instability.cumulative_layout_shift
first_contentful_paint first_contentful_paint
first_input_delay first_input.delay
interaction_to_next_paint interaction_to_next_paint
largest_contentful_paint largest_contentful_paint
experimental_time_to_first_byte experimental.time_to_first_byte
form_factors 不适用

收集期

自 2022 年 10 月起,CrUX API 包含一个 collectionPeriod 对象,该对象包含 firstDateendDate 字段,分别表示汇总期的开始和结束日期。相关示例如下:

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }

这有助于更好地了解数据,以及数据是针对当天进行了更新,还是返回与昨天相同的数据。

请注意,CrUX API 会等待当天完成的数据,因此会比今天晚大约两天。此外,该 API 需要经过一些处理时间才能显示在 API 中。所用时区为太平洋标准时间 (PST),夏令时不变。

示例查询

通过向 https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" 发出 POST 请求,将查询作为 JSON 对象提交,并在 POST 正文中将查询数据作为 JSON 对象提交,例如

{
  "origin": "https://example.com",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

例如,您可以使用以下命令从 curl 进行调用(将 API_KEY 替换为您的键):

curl -s --request POST 'https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=API_KEY' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --data '{"formFactor":"PHONE","origin":"https://www.example.com","metrics":["largest_contentful_paint", "experimental_time_to_first_byte"]}'

通过在查询中传递 url 属性(而不是 origin),即可通过 API 获取网页级数据:

{
  "url": "https://example.com/page",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

如果未设置 metrics 属性,则返回所有可用的指标:

  • cumulative_layout_shift
  • first_contentful_paint
  • first_input_delay
  • interaction_to_next_paint
  • largest_contentful_paint
  • experimental_time_to_first_byte
  • form_factors(仅当请求中未指定 formFactor 时才报告)

如果未提供 formFactor 值,这些值将针对所有外形规格进行汇总。

如需查看更多示例查询,请参阅使用 Chrome UX Report API

数据流水线

CrUX 数据集通过流水线进行处理,以整合、汇总和过滤数据,然后再通过 API 提供。

滚动平均值

Chrome 用户体验报告中的数据是汇总指标的 28 天滚动平均值。也就是说,Chrome 用户体验报告在任意指定时间显示的数据实际上是过去 28 天的数据汇总。

这与 BigQuery 上的 CrUX 数据集汇总月度报告的方式类似。

每日动态

数据每天在世界协调时间 (UTC) 凌晨 04:00 左右更新。更新时间没有服务等级协议;系统会每天尽最大努力执行更新。

架构

CrUX API 只有一个端点,可接受 POST HTTP 请求。该 API 会返回一个 record,其中包含一个或多个 metrics,与所请求源站或网页的性能数据相对应。

HTTP 请求

POST https://chromeuxreport.googleapis.com/v1/records:queryRecord

网址采用 gRPC 转码语法。

请求正文

请求正文应包含结构如下的数据:

{
  "effectiveConnectionType": string,
  "formFactor": enum (FormFactor),
  "metrics": [
    string
  ],

  // Union field url_pattern can be only one of the following:
  "origin": string,
  "url": string
  // End of list of possible types for union field url_pattern.
}
字段
effectiveConnectionType

string

有效连接类型是一个查询维度,用于指定记录的数据应归属的有效网络类。

此字段使用 Network Information API 规范中指定的值 ["offline", "slow-2G", "2G", "3G", "4G"]

注意:如果未指定有效连接类型,则会返回一条特殊记录,其中包含所有有效连接类型的汇总数据。

formFactor

enum (FormFactor)

外形规格是一个查询维度,用于指定记录的数据应归属的设备类别。

此字段使用值 DESKTOPPHONETABLET

注意:如果未指定外形规格,则系统将返回一条特殊记录,其中包含所有外形规格的汇总数据。

metrics[]

string

响应中应包含的指标。如果未指定,则返回找到的任何指标。

允许使用的值:["cumulative_layout_shift", "first_contentful_paint", "first_input_delay", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]

联合字段 url_pattern。网址格式是记录查询的主标识符。它可以是多种类型的值之一。url_pattern 只能是下列其中一项:
origin

string

网址格式“origin”是指作为网站来源的网址格式。

示例:"https://example.com""https://cloud.google.com"

url

string

网址格式“url”是指网址格式,可以是任意网址。

示例:"https://example.com/https://cloud.google.com/why-google-cloud/"

例如,要请求 Chrome 开发者文档首页的桌面设备最大内容渲染值,请使用以下代码:

{
  "url": "https://developer.chrome.com/docs/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

响应正文

成功的请求会返回包含 record 对象和 urlNormalizationDetails 的响应,其结构如下:

{
  "record": {
    "key": {
      object (Key)
    },
    "metrics": [
      string: {
        object (Metric)
      }
    ]
  },
  "urlNormalizationDetails": {
    object (UrlNormalization)
  }
}

例如,上述请求中请求正文的响应可能是:

{
  "record": {
    "key": {
      "formFactor": "DESKTOP",
      "url": "https://developer.chrome.com/docs/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.98148451581189577
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.010814353596591841
          },
          {
            "start": 4000,
            "density": 0.0077011305915124116
          }
        ],
        "percentiles": {
          "p75": 651
        }
      }
    },
    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }
  }
}

Key 定义了将此记录标识为唯一的所有维度。

{
  "effectiveConnectionType": string,
  "formFactor": enum (FormFactor),

  // Union field url_pattern can be only one of the following:
  "origin": string,
  "url": string
  // End of list of possible types for union field url_pattern.
}
字段
formFactor

enum (FormFactor)

外形规格是所有用户用于访问相应记录的网站的设备类别。

如果未指定外形规格,则返回所有外形规格的汇总数据。

effectiveConnectionType

string

有效连接类型是指所有用户针对此记录遇到的常规连接类别。此字段使用 https://wicg.github.io/netinfo/#effective-connection-types 中指定的值 ["offline", "slow-2G", "2G", "3G", "4G"]

如果未指定有效连接类型,则返回所有有效连接类型的汇总数据。

联合字段 url_pattern。网址格式是记录所应用到的网址。url_pattern 只能是下列其中一项:
origin

string

Origin 指定了此记录所属的来源。

注意:指定来源时,此来源下所有网页的加载数据都将汇总到来源级别的用户体验数据中。

url

string

Url 指定此记录所属的特定网址。

注意:在指定“网址”时,系统只会汇总该特定网址的数据。

指标

metric 是针对单个网页性能指标(例如首次内容渲染)的一组汇总用户体验数据。它可能包含真实 Chrome 使用情况的摘要直方图(即一系列 bins)、特定百分位数据(例如 p75),也可能包含带标签的分数。

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

{
  "fractions": {
    object (Fractions)
  }
}
字段
histogram[]

object (Bin)

指标的用户体验直方图。直方图将至少有一个分箱,并且所有分箱的密度加起来约为 1。

percentiles

object (Percentiles)

指标的常见实用百分位。百分位的值类型将与直方图分箱指定的值类型相同。

fractions

object (Fractions)

此对象包含带标签的分数,这些分数相加约为 1。

分箱

bin 是从开始到结束,或者在没有从开始到正无穷大的结束位置作为数据的离散部分。

分箱的起始值和结束值根据其所代表的指标的值类型指定。例如,First Contentful Paint 以毫秒为单位进行测量,并以整数形式公开,因此其指标分箱将使用 int32s 作为其起始和结束类型。不过,累计布局偏移是以无单位为小数的方式进行衡量,并以编码为字符串的十进制形式提供,因此其指标箱将使用字符串作为其值类型。

{
  "start": value,
  "end": value,
  "density": number
}
字段
start

value (Value format)

起始点为数据箱的起始位置。

end

value (Value format)

end 是指数据箱的末尾。如果未填充 end,则表示分箱没有结尾,并且从 start 到 +inf 期间有效。

density

number

在给定指标方面,遇到此分箱值的用户所占的比例。

百分位

Percentiles 包含指标的给定统计百分位的合成值。这些指标用于估算某个指标值,即用户总数中一定百分比的用户所体验到的指标值。

{
  "P75": value
}
字段
p75

value (Value format)

75% 的用户所体验到的指定指标等于或低于此值。

分数

Fractions 包含带标签的分数,这些分数相加约为 1。每个标签都以某种方式描述一次网页加载,因此以这种方式表示的指标可被视为生成不同的值而不是数值,并且分数表示特定不同值的测量频率。

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

与直方图分箱中的密度值非常相似,每个 fraction 都是一个数字 0.0 <= value <= 1.0,它们加起来约为 1.0。

UrlNormalization

此对象表示为实现更高的成功查找几率而对网址进行标准化而采取的标准化操作。这些是在查询提供的 url_pattern(已知失败)时执行的自动更改。系统不会处理跟踪重定向等复杂操作。

{
  "originalUrl": string,
  "normalizedUrl": string
}
字段
originalUrl

string

在执行任何标准化操作之前请求的原始网址。

normalizedUrl

string

执行任何标准化操作后的网址。这是有效的用户体验网址,可合理查询。

速率限制

CrUX API 的限制为每个 Google Cloud 项目每分钟 150 次查询(免费提供)。您可以在 Google Cloud 控制台中查看此限制以及您当前的用量。这种宽裕的配额应该已足以满足绝大多数用例的需求,而且目前还无法为增加的配额付费。