Chrome UX Report API を使用して、何百万ものウェブサイトにおける実際のユーザー エクスペリエンス データを利用する方法をご確認ください。
Chrome UX Report(CrUX)データセットは、Chrome ユーザーがウェブ上の人気ページに実際にアクセスしたときの体験を表しています。クエリ可能なデータセットが初めて BigQuery でリリースされた 2017 年以降、CrUX のフィールド データが PageSpeed Insights、CrUX ダッシュボード、Search Console の Core Web Vitals レポートなどのデベロッパー ツールに統合され、デベロッパーが実際のユーザー エクスペリエンスを測定、モニタリングできるようになりました。これまでずっと不足していたのは、プログラムで CrUX データへの RESTful アクセスを無料で提供するツールです。このたび、このギャップを埋めるべく、まったく新しい Chrome UX Report API をリリースすることになりました。
この API は、デベロッパーが CrUX データに簡単かつ迅速、包括的にアクセスできることを目標に構築されています。既存の PageSpeed Insights API は Lighthouse のパフォーマンス監査のラボデータもレポートするのとは異なり、CrUX API ではフィールドのユーザー エクスペリエンス データのみがレポートされます。CrUX API は効率的で、ユーザー エクスペリエンス データを迅速に提供できるため、リアルタイム監査アプリケーションに最適です。
デベロッパーが最も重要なすべての指標(Core Web Vitals)にアクセスできるように、CrUX API ではオリジンと URL の両方のレベルで Largest Contentful Paint(LCP)、First Input Delay(FID)、Cumulative Layout Shift(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
コマンドは、次の 3 つの部分で構成されます。
- API の URL エンドポイント(呼び出し元の 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 レスポンスは、ユーザー エクスペリエンスの分布を表すmetricsを含む 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% は、LCP の「良好」なしきい値である 2,500 ミリ秒を下回っています。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"}
{"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 ミリ秒に上昇しています。フォーム ファクタでセグメント化することで、ユーザー エクスペリエンスのより極端な差異が浮き彫りになる可能性があります。
Core Web Vitals のパフォーマンスを評価する
Core Web Vitals プログラムでは、ユーザー エクスペリエンスまたはエクスペリエンスの分布が「良好」と見なされるかどうかの判断に役立つターゲットが定義されています。次の例では、CrUX API と CrUXApiUtil.query
関数を使用して、ウェブページの Core Web Vitals 指標(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}).`)
});
}
結果は、このページが 3 つの指標すべてについて Core Web Vitals の評価に合格していることを示しています。
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 データセットを使用しているユーザーは、次のような高度な機能を使い慣れているかもしれません。
- その他の指標
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)で Google をフォローしてください。