如何使用 CrUX API

瞭解如何使用 Chrome UX Report API，取得數百萬個網站的實際使用者體驗資料。

Rick Viscomi

Shane Exterkamp

Chrome UX 報告 (CrUX) 資料集代表 Chrome 使用者實際造訪熱門網頁的體驗。自 2017 年可查詢的資料集首次在 BigQuery 上發布以來，CrUX 的欄位資料已整合至 PageSpeed Insights、CrUX 資訊主頁和 Search Console 的 Core Web Vitals 報告等開發人員工具，方便開發人員評估及監控實際使用者體驗。這段期間缺少的部分，就是提供免費且可透過程式設計以 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)、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"}'

注意：所有 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/"}'

這個 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 毫秒。依據板型規格進行區隔，可能會凸顯使用者體驗的極端差異。

評估 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 及其評估方式，請參閱「網站體驗核心指標」和「評估 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 (歐洲中部時間)
• 其他精細程度
  • 詳細的直方圖
  • 更多百分位數

請參閱官方的 CrUX API 說明文件，取得 API 金鑰，並查看更多應用程式範例。希望您能試試這個功能，我們也非常樂意聆聽您對此功能的任何問題或意見回饋，歡迎前往 CrUX 討論論壇與我們聯絡。如要隨時掌握 CrUX API 的最新消息，請訂閱 CrUX 公告論壇，或在 Twitter 上追蹤 @ChromeUXReport。