このページは Cloud Translation API によって翻訳されました。

CrUX API の使用方法

Chrome UX レポート API を使用して、数百万ものウェブサイトの実際のユーザーエクスペリエンスデータにアクセスする方法について説明します。

Rick Viscomi

Shane Exterkamp

Chrome UX レポート（CrUX）データセットは、Chrome ユーザーがウェブ上の人気ページに実際にアクセスしたときのユーザーエクスペリエンスを表しています。2017 年にクエリ可能なデータセットが BigQuery で初めてリリースされて以来、CrUX のフィールドデータは PageSpeed Insights や Search Console のウェブに関する主な指標レポートなどのデベロッパーツールに統合され、デベロッパーは実際のユーザーエクスペリエンスを測定、モニタリングできるようになりました。これまで欠けていたのは、CrUX データにプログラムで無料で RESTful にアクセスできるツールでした。このギャップを埋めるため、まったく新しい Chrome UX レポート API のリリースを発表いたします。

この API は、デベロッパーが CrUX データに迅速かつ包括的にアクセスできるようにすることを目的として構築されています。CrUX API は、フィールドのユーザーエクスペリエンスデータのみをレポートします。既存の PageSpeed Insights API とは異なり、Lighthouse パフォーマンス監査のラボデータもレポートしません。CrUX API は効率化されており、ユーザーエクスペリエンスデータを迅速に提供できるため、リアルタイムの監査アプリケーションに最適です。

デベロッパーが最も重要な指標である Core Web Vitals にアクセスできるように、CrUX API はオリジンと URL の両方のレベルで 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 コマンドは次の 3 つの部分で構成されています。

呼び出し元の非公開 API キーを含む API の URL エンドポイント。
リクエスト本文に JSON が含まれていることを示す Content-Type: application/json ヘッダー。
https://web.dev オリジンを指定する JSON エンコードされたリクエスト本文。

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 のすべてのページで LCP のユーザーエクスペリエンスの 79% が 2,500 ミリ秒未満です。これは LCP の「良好」のしきい値です。percentiles.p75 の値は、この分布のユーザーエクスペリエンスの 75% が 2,216 ミリ秒未満であることを意味します。レスポンスの構造の詳細については、レスポンス本文のドキュメントをご覧ください。

エラー

CrUX API に特定のオリジンのデータがない場合、JSON エンコードされたエラーメッセージが返されます。

{
  "error": {
    "code": 404,
    "message": "chrome ux report data not found",
    "status": "NOT_FOUND"
  }
}

このエラーをデバッグするには、まずリクエストされたオリジンが一般公開されていることを確認します。これをテストするには、ブラウザのアドレスバーに配信元を入力し、リダイレクト後の最終ページ URL と比較します。一般的な問題としては、サブドメインの追加や省略が不要であるにもかかわらず追加または省略されている、HTTP プロトコルが間違っているなどがあります。

エラー

{"origin": "http://www.web.dev"}

このオリジンには、http:// プロトコルと www. サブドメインが誤って含まれています。

成功

{"origin": "https://web.dev"}

このオリジンは一般公開されています。

リクエストされたオリジンがナビゲーション可能なバージョンである場合、オリジンのサンプル数が不足していると、このエラーが発生することがあります。データセットに含まれるすべてのオリジンと URL には、個々のユーザーを匿名化するのに十分な数のサンプルが必要です。また、オリジンと URL は一般公開されてインデックス登録可能である必要があります。データセットにウェブサイトがどのように含まれているかについて詳しくは、CrUX の方法論をご覧ください。

URL データをクエリする

ここでは、オリジンの全体的なユーザーエクスペリエンスについて 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 データをクエリするには、リクエスト本文の url パラメータを使用して CrUXApiUtil.query 関数を呼び出します。

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

この URL のデータが 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/ の LCP が「良好」なエクスペリエンスの割合は 85% で、75 パーセンタイルは 1,947 ミリ秒です。これは、オリジン全体の分布よりもわずかに優れています。

URL の正規化

CrUX API は、既知の URL のリストとより一致するように、リクエストされた URL を正規化することがあります。たとえば、URL 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 ドキュメントで URL の正規化についてご確認ください。

フォームファクタ別にクエリする

ユーザーエクスペリエンスは、ウェブサイトの最適化、ネットワークの状況、ユーザーのデバイスによって大きく異なる可能性があります。これらの違いをより深く理解するには、CrUX API の formFactor ディメンションを使用して、オリジンと URL のパフォーマンスを詳しく調べます。

この API は、DESKTOP、PHONE、TABLET の 3 つの明示的なフォームファクタ値をサポートしています。オリジンまたは URL に加えて、リクエスト本文で次のいずれかの値を指定して、結果をそれらのユーザーエクスペリエンスのみに制限します。この例では、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 関数を使用して、ウェブページの 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}).`)
  });
}

結果を見ると、このページは 3 つの指標すべてでウェブに関する主な指標のテストに合格しています。

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).

CrUX のデータは、API の結果を自動的にモニタリングする方法と組み合わせることで、実際のユーザーエクスペリエンスが高速化され、高速な状態が維持されるようにするために使用できます。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
追加の粒度
- 詳細なヒストグラム
- パーセンタイルを増やす

公式の CrUX API ドキュメントで、API キーを取得し、その他のサンプルアプリケーションをご覧ください。ぜひお試しください。ご質問やフィードバックがございましたら、CrUX ディスカッションフォーラムまでお寄せください。CrUX API の今後の予定については、CrUX のお知らせフォーラムに登録するか、Twitter の @ChromeUXReport をフォローしてください。

CrUX API の使用方法 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

このページの API を試す

オリジンデータをクエリする

エラー

URL データをクエリする

URL の正規化

フォーム ファクタ別にクエリする

ウェブに関する主な指標のパフォーマンスを評価する

次のステップ

CrUX API の使用方法

フォームファクタ別にクエリする