了解如何使用 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"}
此来源错误地包含 http:// 协议和 www. 子网域。
{"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_paintdom_content_loadedonloadtime_to_first_bytenotification_permissions
- 其他维度
monthcountryeffective connection type（厄瓜多尔）
- 更精细
- 详细直方图
- 更多百分位
请参阅官方 CrUX API 文档，获取您的 API 密钥，并探索更多示例应用。我们希望您能试一试，我们很想听听您的任何问题或反馈，因此请通过 CrUX 论坛与我们联系。如需随时了解我们为 CrUX API 制定的一切计划，请订阅 CrUX 公告论坛，或在 Twitter 上关注我们 (@ChromeUXReport)。