了解如何使用 Chrome UX Report API 获取数百万个网站上的真实用户体验数据。
Chrome 用户体验报告 (CrUX) 数据集反映了真实的 Chrome 用户在网络上体验热门目标页面的情况。自 2017 年在 BigQuery 上首次发布可查询数据集时,CrUX 中的实测数据已集成到 PageSpeed Insights、CrUX 信息中心和 Search Console 的“核心网页指标”报告等开发者工具中,让开发者能够衡量和监控实际用户体验。一直以来都缺少一种工具,它可以通过编程方式免费以 RESTful 访问 CrUX 数据。为了弥补这一缺口,我们很高兴地宣布,我们将发布全新的 Chrome 用户体验报告 API!
此 API 旨在为开发者提供简单、快速且全面的 CrUX 数据访问功能。与现有的 PageSpeed Insights API 不同,CrUX API 仅报告字段用户体验数据,后者也会报告来自 Lighthouse 性能审核的实验室数据。CrUX API 经过简化,可以快速提供用户体验数据,因此非常适合实时审核应用。
为确保开发者能够访问最重要的所有指标(核心网页指标),CrUX API 会在源站和网址层级审核并监控 Largest Contentful Paint (LCP)、First Input Delay (FID) 和 Cumulative Layout Shift (CLS)。
下面我们就来深入了解一下如何使用它!
查询源数据
CrUX 数据集中的源点涵盖所有底层网页级体验。以下示例演示了如何在命令行中使用 c网址 向 CrUX API 查询源的用户体验数据。
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"origin": "https://web.dev"}'
curl
命令由三部分组成:
- API 的网址端点,包括调用方的私有 API 密钥。
Content-Type: application/json
标头,表示请求正文包含 JSON。- 采用 JSON 编码的请求正文,用于指定
https://web.dev
来源。
如需在 JavaScript 中执行相同的操作,请使用 CrUXApiUtil
实用程序,该实用程序会进行 API 调用并返回解码的响应(另请参阅我们的 GitHub 变体,了解更多功能,包括历史记录和批量支持)。
const CrUXApiUtil = {};
// Get your CrUX API key at https://goo.gle/crux-api-key.
CrUXApiUtil.API_KEY = '[YOUR_API_KEY]';
CrUXApiUtil.API_ENDPOINT = `https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=${CrUXApiUtil.API_KEY}`;
CrUXApiUtil.query = function (requestBody) {
if (CrUXApiUtil.API_KEY == '[YOUR_API_KEY]') {
throw 'Replace "YOUR_API_KEY" with your private CrUX API key. Get a key at https://goo.gle/crux-api-key.';
}
return fetch(CrUXApiUtil.API_ENDPOINT, {
method: 'POST',
body: JSON.stringify(requestBody)
}).then(response => response.json()).then(response => {
if (response.error) {
return Promise.reject(response);
}
return response;
});
};
将 [YOUR_API_KEY]
替换为您的键。接下来,调用 CrUXApiUtil.query
函数并传入请求正文对象。
CrUXApiUtil.query({
origin: 'https://web.dev'
}).then(response => {
console.log(response);
}).catch(response => {
console.error(response);
});
如果此源存在数据,则 API 响应是一个 JSON 编码对象,其中包含表示用户体验分布的metrics。分布指标是直方图分箱和百分位数。
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [
{
"start": 0,
"end": 2500,
"density": 0.7925068547983514
},
{
"start": 2500,
"end": 4000,
"density": 0.1317422195536863
},
{
"start": 4000,
"density": 0.07575092564795324
}
],
"percentiles": {
"p75": 2216
}
},
// ...
}
}
}
histogram
对象的 start
和 end
属性表示对于给定指标,用户体验的值范围。density
属性表示用户体验在该范围内所占的百分比。在本例中,所有 web.dev 网页中 79% 的 LCP 用户体验低于 2,500 毫秒,这是“良好”LCP 阈值。percentiles.p75
值表示此分布中 75% 的用户体验小于 2,216 毫秒。如需详细了解响应结构,请参阅响应正文文档。
错误
当 CrUX API 没有任何给定来源的数据时,它会以 JSON 编码的错误消息作为响应:
{
"error": {
"code": 404,
"message": "chrome ux report data not found",
"status": "NOT_FOUND"
}
}
如需调试此错误,请先检查请求的来源是否可公开导航。要进行测试,您可以在浏览器的地址栏中输入来源,并在所有重定向后将其与最终到达网址进行比较。常见问题包括不必要地添加或省略子网域以及使用了错误的 HTTP 协议。
{"origin": "http://www.web.dev"}
{"origin": "https://web.dev"}
如果请求的来源是可导航版本,那么当来源中的样本数量不足时,也可能会出现此错误。数据集内包含的所有源站和网址都必须有足够的样本,才能对单个用户进行匿名化处理。此外,源和网址必须可公开编入索引。请参阅 CrUX 方法,详细了解如何将网站纳入数据集。
查询网址数据
您已经了解如何在源上查询 CrUX API 以获取整体用户体验。如需将结果限制为特定网页,请使用 url
请求参数。
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url": "https://web.dev/fast/"}'
此 c网址 命令与源示例类似,只不过请求正文使用 url
参数指定要查找的网页。
如需使用 JavaScript 查询来自 CrUX API 的网址数据,请在请求正文中使用 url
参数调用 CrUXApiUtil.query
函数。
CrUXApiUtil.query({
url: 'https://web.dev/fast/'
}).then(response => {
console.log(response);
}).catch(response => {
console.error(response);
});
如果 CrUX 数据集中存在此网址的数据,则该 API 会返回采用 JSON 编码的响应。例如:
{
"record": {
"key": {
"url": "https://web.dev/fast/"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [
{
"start": 0,
"end": 2500,
"density": 0.8477304539092148
},
{
"start": 2500,
"end": 4000,
"density": 0.08988202359528057
},
{
"start": 4000,
"density": 0.062387522495501155
}
],
"percentiles": {
"p75": 1947
}
},
// ...
}
}
}
事实证明,https://web.dev/fast/
的 LCP 体验为 85%,为 1,947 毫秒,第 75 个百分位为 1,947 毫秒,这略优于源范围分布。
网址标准化
CrUX API 可能会对所请求的网址进行标准化,以便更好地匹配已知网址列表。例如,由于标准化处理,查询网址 https://web.dev/fast/#measure-performance-in-the-field
将导致 https://web.dev/fast/
的数据。发生这种情况时,响应中会包含一个 urlNormalizationDetails
对象。
{
"record": {
"key": {
"url": "https://web.dev/fast/"
},
"metrics": { ... }
},
"urlNormalizationDetails": {
"normalizedUrl": "https://web.dev/fast/",
"originalUrl": "https://web.dev/fast/#measure-performance-in-the-field"
}
}
如需详细了解网址标准化,请参阅 CrUX 文档。
按设备规格查询
用户体验可能会因网站优化情况、网络条件和用户的设备而异。如需更好地了解这些差异,请使用 CrUX API 的 formFactor
维度深入分析来源和网址的效果。
该 API 支持三种明确的外形规格值:DESKTOP
、PHONE
和 TABLET
。除了来源或网址之外,请在请求正文中指定其中一个值,以将结果限制为仅显示相应用户体验。此示例演示了如何使用 c网址 按设备规格查询 API。
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url": "https://web.dev/fast/", "formFactor": "PHONE"}'
如需使用 JavaScript 向 CrUX API 查询外形规格专属数据,请在请求正文中使用 url
和 formFactor
参数调用 CrUXApiUtil.query
函数。
CrUXApiUtil.query({
url: 'https://web.dev/fast/',
formFactor: 'PHONE'
}).then(response => {
console.log(response);
}).catch(response => {
console.error(response);
});
省略 formFactor
参数相当于为所有外形规格请求数据。
{
"record": {
"key": {
"url": "https://web.dev/fast/",
"formFactor": "PHONE"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [
{
"start": 0,
"end": 2500,
"density": 0.778631284916204
},
{
"start": 2500,
"end": 4000,
"density": 0.13943202979515887
},
{
"start": 4000,
"density": 0.08193668528864119
}
],
"percentiles": {
"p75": 2366
}
},
// ...
}
}
}
响应的 key
字段将回显 formFactor
请求配置,以确认仅包含手机体验。
还记得吗,上一部分中有 85% 的用户体验具有“良好”的 LCP。相比之下,手机专用体验只有 78% 被视为“良好”。在手机体验中,第 75 百分位的运行速度也较慢,从 1,947 毫秒增加到 2,366 毫秒。按设备规格细分有可能凸显用户体验中的巨大差异。
评估 Core Web Vitals 性能
核心网页指标计划定义了一些目标,有助于确定用户体验或体验分发是否属于“良好”体验。在以下示例中,我们会使用 CrUX API 和 CrUXApiUtil.query
函数来评估网页的 Core Web Vitals 指标(LCP、FID、CLS)分布是否“良好”。
CrUXApiUtil.query({
url: 'https://web.dev/fast/'
}).then(response => {
assessCoreWebVitals(response);
}).catch(response => {
console.error(response);
});
function assessCoreWebVitals(response) {
// See https://web.dev/vitals/#core-web-vitals.
const CORE_WEB_VITALS = [
'largest_contentful_paint',
'first_input_delay',
'cumulative_layout_shift'
];
CORE_WEB_VITALS.forEach(metric => {
const data = response.record.metrics[metric];
if (!data) {
console.log('No data for', metric);
return;
}
const p75 = data.percentiles.p75;
const threshold = data.histogram[0].end;
// A Core Web Vitals metric passes the assessment if
// its 75th percentile is under the "good" threshold.
const passes = p75 < threshold;
console.log(`The 75th percentile (${p75}) of ${metric} ` +
`${passes ? 'passes' : 'does not pass'} ` +
`the Core Web Vitals "good" threshold (${threshold}).`)
});
}
结果显示,此网页通过了全部三项指标的核心网页指标评估。
The 75th percentile (1973) of largest_contentful_paint passes the Core Web Vitals "good" threshold (2500).
The 75th percentile (20) of first_input_delay passes the Core Web Vitals "good" threshold (100).
The 75th percentile (0.05) of cumulative_layout_shift passes the Core Web Vitals "good" threshold (0.10).
结合用于监控 API 结果的自动化方法,CrUX 中的数据可用于确保真实用户体验快速且保持快速。如需详细了解核心网页指标及其衡量方法,请参阅网页指标和衡量核心网页指标的工具。
后续操作
CrUX API 初始版本中包含的功能只是冰山一角的 CrUX 可能的数据洞见。BigQuery 中的 CrUX 数据集的用户可能熟悉一些更高级的功能,包括:
- 其他指标
first_paint
dom_content_loaded
onload
time_to_first_byte
notification_permissions
- 其他维度
month
country
effective connection type
(厄瓜多尔)
- 更精细
- 详细直方图
- 更多百分位
请参阅官方 CrUX API 文档,获取您的 API 密钥,并探索更多示例应用。我们希望您能试一试,我们很想听听您的任何问题或反馈,因此请通过 CrUX 论坛与我们联系。如需随时了解我们为 CrUX API 制定的一切计划,请订阅 CrUX 公告论坛,或在 Twitter 上关注我们 (@ChromeUXReport)。