借助 CrUX API,您可以低延迟访问基于页面和源粒度的汇总真实用户体验数据。
常见用例
借助 CrUX API,您可以查询特定 URI 的用户体验指标,例如“获取 https://example.com
源的指标”。
CrUX API 密钥
若要使用 CrUX API,您需要针对 Chrome UX Report API
使用预配 Google Cloud API 密钥。
获取和使用 API 密钥
获取密钥或者在“凭据”页面中创建一个。
在您获得 API 密钥后,您的应用便可在所有请求网址后附加查询参数 key=yourAPIKey
。
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.html
和 http://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
,则表示记录包含移动设备上发生的加载的相关信息。每个维度都有一定数量的值,如果不指定该维度,就意味着该维度将针对所有值进行汇总。例如,如果未指定任何外形规格,则表示记录包含与任何外形规格上发生的加载相关的信息。
设备规格
最终用户用于导航到页面的设备类别。这是一个常规类,可分为 PHONE
、TABLET
和 DESKTOP
。
有效连接类型
有效连接类型是指前往相应页面时设备的估算连接质量。这是一个分为 offline
、slow-2G
、2G
、3G
和 4G
的常规类。
指标
我们以直方图、百分位和分数等统计汇总形式报告指标。
浮点值会四舍五入到小数点后 4 位(请注意,cumulative_layout_shift
指标是作为字符串编码的双精度值,因此不考虑浮点值,并且会报告到字符串中的 2 位小数)。
直方图
当指标以直方图表示时,我们会显示归入该类别的网页加载次数所占的百分比 该指标的特定范围
示例指标的三个分箱直方图如下所示:
{
"histogram": [
{
"start": 0,
"end": 1000,
"density": 0.3818
},
{
"start": 1000,
"end": 3000,
"density": 0.4991
},
{
"start": 3000,
"density": 0.1192
}
]
}
这些数据表明,对于 38.18% 的网页加载,示例指标是 介于 0 毫秒到 1,000 毫秒之间。此直方图中不包含指标的单位 在此示例中,我们将假定为毫秒级。
此外,49.91% 的网页加载看到的指标值介于 1,000 毫秒到 3,000 毫秒之间,11.92% 的网页加载时间 检测到大于 3,000 毫秒的值
百分位
指标还可能包含可用于进一步分析的百分位。 我们会在该指标的指定百分位报告特定指标值。 它们基于完整的可用数据集,而不是最终的分箱数据。 因此它们不一定与根据实际数据 最终的分箱直方图。
{
"percentiles": {
"p75": 2063
}
}
在此示例中,至少有 75% 的网页加载是通过指标值 <= 2063
衡量的。
分数
分数表示可以采用特定方式标记的网页加载次数所占的百分比。 在本例中,指标值就是这些标签。
例如,form_factors
指标包含一个 fractions
对象,其中列出了给定查询涵盖的外形规格(或设备)的细分维度:
"form_factors": {
"fractions": {
"desktop": 0.0377,
"tablet": 0.0288,
"phone": 0.9335
}
}
在该案例中,3.77% 的网页加载是在桌面设备上测得的,2.88% 是在平板电脑上,93.35% 在手机上测得,总计 100%。
指标值类型
CrUX API 指标名称 | 数据类型 | 公制单位 | 统计汇总 | 文档 |
---|---|---|---|---|
cumulative_layout_shift |
2 位小数双编码为字符串 | 无单位 | 包含三个分箱的直方图,百分位数为 p75 | cls |
first_contentful_paint |
int | 毫秒 | 包含三个分箱的直方图,百分位数为 p75 | FCP |
first_input_delay (已弃用) |
int | 毫秒 | 包含三个分箱的直方图,百分位数为 p75 | |
interaction_to_next_paint |
int | 毫秒 | 包含三个分箱的直方图,百分位数为 p75 | INP |
largest_contentful_paint |
int | 毫秒 | 包含三个分箱的直方图,百分位数为 p75 | lcp |
experimental_time_to_first_byte |
int | 毫秒 | 包含三个分箱的直方图,百分位数为 p75 | ttfb |
form_factors |
4 位小数 | 百分比 | 从设备规格映射到比例 | 外形规格 |
navigation_types |
4 位小数 | 百分比 | 从导航类型映射到分数 | 导航类型 |
round_trip_time |
int | 毫秒 | 百分位数为 p75 | rtt |
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 |
navigation_types |
navigation_types |
form_factors |
不适用 |
round_trip_time |
不适用 |
收集期
自 2022 年 10 月起,CrUX API 包含一个 collectionPeriod
对象,其中包含表示汇总期的开始日期和结束日期的 firstDate
和 endDate
字段。例如:
"collectionPeriod": {
"firstDate": {
"year": 2022,
"month": 9,
"day": 12
},
"lastDate": {
"year": 2022,
"month": 10,
"day": 9
}
}
这样,您就可以更好地了解数据,并确定当天是更新的数据,还是返回与昨天相同的数据。
请注意,CrUX 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"]}'
若要通过该 API 获得网页级数据,请在查询中传递 url
属性(而非 origin
):
{
"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
navigation_types
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 |
有效连接类型是一个查询维度,用于指定记录的数据应属于的有效网络类。 此字段使用 Network Information API 规范中指定的值 注意:如果未指定有效连接类型,则系统将返回一条特殊记录,其中包含所有有效连接类型的汇总数据。 |
formFactor |
外形规格是一个查询维度,用于指定记录的数据应属于哪个设备类。 此字段使用的值包括 注意:如果未指定外形规格,系统将返回一条特殊记录,其中包含针对所有外形规格的汇总数据。 |
metrics[] |
响应中应包含的指标。如果未指定,则返回找到的所有指标。 允许使用的值: |
联合字段 url_ 。url_pattern 是记录查询的主要标识符。它只能是下列其中一项: |
|
origin |
示例: |
url |
示例: |
例如,要为 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.9815
},
{
"start": 2500,
"end": 4000,
"density": 0.0108
},
{
"start": 4000,
"density": 0.0077
}
],
"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 |
设备规格是指用于访问此记录的网站的设备类别。 如果未指定外形规格,系统将返回所有外形规格的汇总数据。 |
effectiveConnectionType |
有效连接类型是所有用户在遇到该记录时遇到的常规连接类别。此字段使用的值 ["offline", "slow-2G", "2G", "3G", "4G"],详见 https://wicg.github.io/netinfo/#effective-connection-types 如果未指定有效连接类型,系统将返回所有有效连接类型的汇总数据。 |
联合字段 url_ 。网址格式是记录适用的网址。url_ 只能是下列其中一项: |
|
origin |
注意:如果指定 |
url |
注意:指定 |
指标
metric
是单个网页性能指标(例如首次内容渲染)的一组汇总用户体验数据。
其中可能包含实际 Chrome 使用情况的汇总直方图(显示为一系列特定百分位数据)bins
(如 p75),也可能包含带标签的部分。
{
"histogram": [
{
object (Bin)
}
],
"percentiles": {
object (Percentiles)
}
}
或
{
"fractions": {
object (Fractions)
}
}
字段 | |
---|---|
histogram[] |
指标的用户体验直方图。直方图将至少有一个分箱,并且所有分箱的密度加起来约为 1。 |
percentiles |
指标的常见实用百分位数。百分位的值类型与为直方图分箱指定的值类型相同。 |
fractions |
此对象包含已加标签的分数,这些分数加起来约为 1。 分数会四舍五入到小数点后 4 位。 |
分箱
bin
是数据中从开始到结束的离散部分,或者如果从开始到正无穷大没有指定结束值。
分箱的起始值和结束值以其所代表的指标的值类型指定。例如,First Contentful Paint 以毫秒为单位进行测量,并以 int 的形式公开,因此其指标 bin 将使用 int32s 作为 start 和 end 类型。不过,累积布局偏移以无单位的小数进行衡量,并以字符串编码的形式公开,因此其指标分箱将使用字符串作为其值类型。
{
"start": value,
"end": value,
"density": number
}
字段 | |
---|---|
start |
起始位置是数据箱的起始位置。 |
end |
End 是数据箱的末端。如果未填充结束值,则分箱没有结束值,并且从 start 到 +inf 期间有效。 |
density |
就给定指标而言,遇到过此分箱值的用户所占的比例。 密度四舍五入到小数点后 4 位。 |
百分位
Percentiles
包含指标在指定统计百分位的合成值。这些指标用于估算用户总数中一定比例的用户所体验到的指标值。
{
"P75": value
}
字段 | |
---|---|
p75 |
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 |
在执行任何标准化操作之前请求的原始网址。 |
normalizedUrl |
执行任何标准化操作后的网址。这是有效用户体验网址,可以通过合理查找。 |
速率限制
CrUX API 限制为每个 Google Cloud 项目的每分钟 150 次查询,这是免费的。您可以在 Google Cloud 控制台中查看此限额和您当前的用量。这种宽裕的配额应该足以满足绝大多数用例的需要,并且无法为增加的配额付费。