如何使用 CrUX API

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

Rick Viscomi

Shane Exterkamp

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

此 API 旨在让开发者能够轻松、快速且全面地访问 CrUX 数据。CrUX API 仅报告实测用户体验数据，而现有的 PageSpeed Insights API 还会报告 Lighthouse 性能审核中的实验数据。CrUX API 经过精简，可以快速提供用户体验数据，非常适合实时审核应用。

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

接下来，我们就来深入了解一下该工具的使用方式！

在此页面上试用 API

试试看！

查询来源数据

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

注意：所有 API 请求都必须为 key 参数提供值，前面的示例中的 [YOUR_API_KEY] 是作为占位符保留的。获取您自己的私钥 CrUX API 密钥，如 CrUX API 文档中所述。

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 属性表示在该范围内的用户体验所占的比例。在此示例中，79% 的 web.dev 网页的 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/ 有 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。除了来源或网址之外，您还可以在请求正文中指定以下值之一，以将结果仅限于这些用户体验。此示例演示了如何使用 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、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}).`)
  });
}

要点：一次只能使用一个来源或网址调用该 API。如需评估多个网站或网页，请单独调用该 API。

结果显示，此网页在所有三个 Core Web Vitals 指标方面都通过了评估。

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 中的数据确保真实用户体验快速启动并保持快速。如需详细了解 Core Web Vitals 及其衡量方法，请参阅 Web Vitals 和衡量 Core Web Vitals 的指标工具。

后续操作

CrUX API 初始版本中包含的功能只是 CrUX 可提供的数据分析类型的一小部分。BigQuery 中的 CRUX 数据集的用户可能熟悉一些更高级的功能，包括：

• 其他指标
  • first_paint
  • dom_content_loaded
  • onload
  • time_to_first_byte
  • notification_permissions
• 其他维度
  • month
  • country
  • effective connection type (ECT)
• 更多细分
  • 详细的直方图
  • 更多百分位数

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