如何使用 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 经过简化，可以快速提供用户体验数据，因此非常适合实时审核应用。

为确保开发者能够访问所有最重要的指标，即 Core Web Vitals，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"}'

注意：所有 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 属性表示该范围内用户体验的比例。在此示例中，所有 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/ 的“良好”率为 85%LCP 体验为 1,947 毫秒，为第 75 个百分位，略优于整个源范围内的分布。

网址标准化

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 性能

Core Web Vitals 计划定义了一些目标，用来帮助确定用户体验或体验分布是否可被视为“良好”。在以下示例中，我们使用 CrUX API 和 CrUXApiUtil.query 函数来评估网页的核心网页指标（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}).`)
  });
}

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

结果显示，此网页通过所有三个指标的“核心网页指标”评估。

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

后续操作

CrUX API 初始版本中包含的功能只是冰山一角，因为 CrUX 能够获得哪些类型的数据分析。BigQuery 上的 CrUX 数据集的用户可能熟悉一些更高级的功能，包括：

• 其他指标 <ph type="x-smartling-placeholder">
  </ph>
  • first_paint
  • dom_content_loaded
  • onload
  • time_to_first_byte
  • notification_permissions
• 其他维度 <ph type="x-smartling-placeholder">
  </ph>
  • month
  • country
  • effective connection type（厄瓜多尔）
• 其他细化程度 <ph type="x-smartling-placeholder">
  </ph>
  • 详细直方图
  • 更多百分位

请参阅官方 CrUX API 文档以获取您的 API 密钥，并探索更多示例应用。希望您试试看。我们非常期待收到您的任何问题或反馈，欢迎通过 CrUX 论坛与我们联系。如需及时了解我们针对 CrUX API 制定的所有计划，请订阅 CrUX 公告论坛，或在 Twitter 上关注我们 (@ChromeUXReport)。