如何使用 CrUX API

了解如何使用 Chrome UX Report API 来访问数百万个网站的真实用户体验数据。

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

Chrome 用户体验报告 (CrUX) 数据集反映了真实的 Chrome 用户在网络上访问热门网址时的体验。自 2017 年在 BigQuery 上首次发布可查询的数据集以来，CrUX 的实测数据已集成到 PageSpeed Insights 等开发者工具和 Search Console 的“核心网页指标”报告中，使开发者能够衡量和监控真实用户体验。一直以来，我们都缺少一个工具，该工具能够以编程方式免费且以 RESTful 方式访问 CrUX 数据。为了帮助弥合这一差距，我们很高兴地宣布推出全新的 Chrome UX Report API！

此 API 的构建目标是为开发者提供对 CrUX 数据的快速而全面的访问权限。与现有的 PageSpeed Insights API 不同，CrUX API 仅报告实测用户体验数据，而后者还会报告 Lighthouse 性能审核中的实验室数据。CrUX API 经过精简，可以快速提供用户体验数据，非常适合实时审核应用。

为了确保开发者能够访问最重要的所有指标（即核心网页指标），CrUX API 会在来源级和网址级审核并监控 Largest Contentful Paint (LCP)、Interaction to Next Paint (INP) 和 Cumulative Layout Shift (CLS)。

下面，我们就来深入了解一下如何使用它！

在此页面上试用 API

试试看！

查询来源数据

CrUX 数据集中的来源涵盖所有底层网页级体验。以下示例演示了如何使用命令行中的 curl 查询 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 命令由三部分组成：

  1. API 的网址端点，包括调用者的私有 API 密钥。
  2. Content-Type: application/json 标头，表示请求正文包含 JSON。
  3. 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 编码的对象，其中包含表示用户体验分布的指标。分布指标是直方图箱和百分位。

{
  "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/"}'

此 curl 命令与源示例类似，不同之处在于请求正文使用 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/ 有 85% 的“良好”LCP 体验，第 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。除了来源或网址之外，您还可以在请求正文中指定以下值之一，以将结果限制为仅包含这些用户体验。此示例演示了如何使用 curl 按设备规格查询 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 毫秒。按设备类型细分有助于突出显示用户体验方面更加明显的差异。

评估核心网页指标表现

核心网页指标计划定义了有助于确定用户体验或体验分布是否可以被视为“良好”的目标。在以下示例中，我们使用 CrUX API 和 CrUXApiUtil.query 函数来评估网页的核心网页指标（LCP、INP、CLS）分布是否“良好”。

CrUXApiUtil.query({
  url: 'https://web.dev/fast/'
}).then(response => {
  assessCoreWebVitals(response);
}).catch(response => {
  console.error(response);
});

function assessCoreWebVitals(response) {
  // See https://web.dev/articles/vitals/#core-web-vitals.
  const CORE_WEB_VITALS = [
    'largest_contentful_paint',
    'interaction_to_next_paint',
    '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 interaction_to_next_paint passes the Core Web Vitals "good" threshold (200).
The 75th percentile (0.05) of cumulative_layout_shift passes the Core Web Vitals "good" threshold (0.10).

结合使用自动监控 API 结果的方法，CrUX 中的数据可用于确保真实用户体验快速且始终快速。如需详细了解核心 Web 指标以及如何衡量这些指标，请参阅 Web 指标和用于衡量核心 Web 指标的工具。

后续操作

初始版 CrUX API 中包含的功能仅揭示了 CrUX 可能提供的部分数据洞见。BigQuery 上的 CrUX 数据集的用户可能熟悉一些更高级的功能，包括：

  • 其他指标
    • first_paint
    • dom_content_loaded
    • onload
    • time_to_first_byte
    • notification_permissions
  • 其他维度
    • month
    • country
  • 其他粒度
    • 详细的直方图
    • 更多百分位

请参阅官方 CrUX API 文档，获取您的 API 密钥并探索更多示例应用。我们希望您能试用一下，并期待收到您的任何问题或反馈，欢迎在 CrUX 讨论论坛中与我们联系。如需及时了解我们为 CrUX API 规划的所有内容，请订阅 CrUX 公告论坛，或在 Twitter 上关注我们，账号为 @ChromeUXReport。