瞭解如何使用 Chrome UX Report API 存取數百萬個網站的實際使用者體驗資料。
Chrome 使用者體驗報告 (CrUX) 資料集可以說明 Chrome 使用者實際造訪熱門網路平台的情形。自 2017 年起，可查詢資料集首次於 BigQuery 推出時，CrUX 欄位資料已經整合到多項開發人員工具，例如 PageSpeed Insights、CrUX 資訊主頁和 Search Console 的網站體驗核心指標報告，讓開發人員能夠評估及監控實際使用者體驗。有鑑於此，我們一直以來所缺少的部分，就是透過程式免費提供且符合 REST 樣式的 CrUX 資料存取工具。為協助消弭這項落差，我們很高興宣布推出全新的 Chrome UX Report API！
這個 API 的目標是讓開發人員以簡單、快速且全面的方式存取 CrUX 資料。CrUX API 只能回報欄位使用者體驗資料，與現有的 PageSpeed Insights API 不同，後者也會回報 Lighthouse 效能稽核的研究室資料。CrUX API 相當精簡，可迅速提供使用者體驗資料，非常適合用於即時稽核應用程式。
為確保開發人員能存取所有重要指標，也就是 Core Web Vitals，也就是 CrUX API 會稽核並監控來源和網址層級的最大內容繪製 (LCP)、首次輸入延遲時間 (FID) 和累計版面配置位移 (CLS)。
讓我們深入瞭解使用方式！
查詢來源資料
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 指令由三個部分組成：
- 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/"}'
這個 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、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(ECT)
- 其他精細程度
- 詳細直方圖
- 更多百分位數
請參閱官方的 CrUX API 文件，取得 API 金鑰並瀏覽更多應用程式範例。希望您能試用並告訴我們任何問題或意見，歡迎透過 CrUX 論壇與我們聯絡。此外，如要隨時掌握我們針對 CrUX API 所做的任何計畫，請訂閱 CrUX 公告論壇，或在 Twitter 上追蹤我們：@ChromeUXReport。