Pelajari cara menggunakan Chrome UX Report API untuk mendapatkan akses ke data pengalaman pengguna nyata di jutaan situs.
Set data Chrome UX Report (CrUX) menunjukkan cara pengguna Chrome di dunia nyata menjelajahi tujuan populer di web. Sejak tahun 2017, saat set data yang dapat dikueri pertama kali dirilis di BigQuery, data kolom dari CrUX telah diintegrasikan ke alat developer seperti PageSpeed Insights, Dasbor CrUX, dan laporan Core Web Vitals di Search Console, sehingga memungkinkan developer mengukur dan memantau pengalaman pengguna nyata. Bagian yang selama ini tidak ada selama ini adalah alat yang menyediakan akses gratis dan RESTful ke data CrUX secara terprogram. Untuk membantu menjembatani kesenjangan tersebut, dengan senang hati kami mengumumkan rilis Chrome UX Report API yang baru!
API ini dibuat dengan tujuan memberikan akses yang sederhana, cepat, dan komprehensif kepada developer ke data CrUX. CrUX API hanya melaporkan data pengalaman pengguna kolom, tidak seperti PageSpeed Insights API saat ini, yang juga melaporkan data lab dari audit performa Lighthouse. CrUX API disederhanakan dan dapat dengan cepat menyajikan data pengalaman pengguna, sehingga sangat cocok untuk aplikasi audit real-time.
Untuk memastikan developer memiliki akses ke semua metrik yang paling penting—Core Web Vitals—mengaudit dan memantau Largest Contentful Paint (LCP), Interaction to Next Paint (INP), dan Pergeseran Tata Letak Kumulatif (CLS) di tingkat asal dan URL.
Jadi, mari kita pelajari lebih lanjut dan lihat cara menggunakannya.
Membuat kueri data asal
Asal dalam set data CrUX mencakup semua pengalaman tingkat halaman yang mendasarinya. Contoh berikut menunjukkan cara mengkueri CrUX API untuk data pengalaman pengguna origin menggunakan cURL di command line.
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"}'
Perintah curl
terdiri dari tiga bagian:
- Endpoint URL API, termasuk kunci API pribadi pemanggil.
- Header
Content-Type: application/json
, yang menunjukkan bahwa isi permintaan berisi JSON. - Isi permintaan berenkode JSON, yang menentukan asal
https://web.dev
.
Untuk melakukan hal yang sama di JavaScript, gunakan utilitas CrUXApiUtil
,
yang melakukan panggilan API dan menampilkan respons yang didekode (lihat juga varian GitHub kami
untuk fitur lainnya, termasuk histori dan dukungan batch).
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;
});
};
Ganti [YOUR_API_KEY]
dengan kunci Anda. Selanjutnya, panggil fungsi CrUXApiUtil.query
dan teruskan objek isi permintaan.
CrUXApiUtil.query({
origin: 'https://web.dev'
}).then(response => {
console.log(response);
}).catch(response => {
console.error(response);
});
Jika data untuk asal ini ada, respons API adalah objek berenkode JSON yang berisi metrik yang mewakili distribusi pengalaman pengguna. Metrik distribusi adalah bin histogram dan persentil.
{
"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
}
},
// ...
}
}
}
Properti start
dan end
objek histogram
mewakili rentang nilai yang dialami pengguna untuk metrik tertentu. Properti density
merepresentasikan proporsi pengalaman pengguna dalam rentang tersebut. Dalam contoh ini, 79% pengalaman pengguna LCP di semua halaman web.dev berada di bawah 2.500 milidetik, yang merupakan status "baik" Nilai minimum LCP. Nilai percentiles.p75
berarti 75% pengalaman pengguna dalam distribusi ini kurang dari 2.216 milidetik. Pelajari struktur respons lebih lanjut dalam dokumentasi isi respons.
Error
Jika CrUX API tidak memiliki data untuk origin tertentu, CrUX API akan merespons dengan pesan error berenkode JSON:
{
"error": {
"code": 404,
"message": "chrome ux report data not found",
"status": "NOT_FOUND"
}
}
Untuk men-debug error ini, periksa terlebih dahulu apakah asal yang diminta dapat dijelajahi secara publik. Anda dapat mengujinya dengan memasukkan origin ke kolom URL browser dan membandingkannya dengan URL final setelah pengalihan. Masalah umum mencakup penambahan atau penghapusan subdomain dan penggunaan protokol HTTP yang salah.
{"origin": "http://www.web.dev"}
{"origin": "https://web.dev"}
Jika origin yang diminta adalah versi yang dapat dinavigasi, error ini juga dapat terjadi jika origin tidak memiliki jumlah sampel yang cukup. Semua origin dan URL yang disertakan dalam set data harus memiliki jumlah sampel yang memadai untuk menganonimkan setiap pengguna. Selain itu, origin dan URL harus dapat diindeks secara publik. Lihat metodologi CrUX untuk mempelajari lebih lanjut bagaimana situs disertakan dalam set data.
Data URL kueri
Anda telah melihat cara membuat kueri CrUX API untuk keseluruhan pengalaman pengguna di origin. Untuk membatasi hasil ke halaman tertentu, gunakan parameter permintaan 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/"}'
Perintah cURL ini mirip dengan contoh asal, kecuali bahwa isi permintaan menggunakan parameter url
untuk menentukan halaman yang akan dicari.
Untuk membuat kueri data URL dari CrUX API di JavaScript, panggil fungsi CrUXApiUtil.query
menggunakan parameter url
dalam isi permintaan.
CrUXApiUtil.query({
url: 'https://web.dev/fast/'
}).then(response => {
console.log(response);
}).catch(response => {
console.error(response);
});
Jika data untuk URL ini ada dalam set data CrUX, API akan menampilkan respons yang dienkode JSON. Contoh:
{
"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
}
},
// ...
}
}
}
Bentuk benar, hasil menunjukkan bahwa https://web.dev/fast/
memiliki 85% status "baik" Pengalaman LCP dan persentil ke-75 sebesar 1.947 milidetik, yang sedikit lebih baik daripada distribusi seluruh origin.
Normalisasi URL
CrUX API dapat menormalisasi URL yang diminta agar lebih cocok dengan daftar URL yang dikenal. Misalnya, kueri untuk URL https://web.dev/fast/#measure-performance-in-the-field
akan menghasilkan data untuk https://web.dev/fast/
karena normalisasi. Jika hal ini terjadi, objek urlNormalizationDetails
akan disertakan dalam respons.
{
"record": {
"key": {
"url": "https://web.dev/fast/"
},
"metrics": { ... }
},
"urlNormalizationDetails": {
"normalizedUrl": "https://web.dev/fast/",
"originalUrl": "https://web.dev/fast/#measure-performance-in-the-field"
}
}
Pelajari normalisasi URL lebih lanjut di dokumentasi CrUX.
Kueri menurut faktor bentuk
Pengalaman pengguna dapat sangat bervariasi, bergantung pada pengoptimalan situs, kondisi jaringan, dan perangkat. Untuk lebih memahami perbedaan ini, lihat perincian performa URL dan origin menggunakan dimensi formFactor
dari CrUX API.
API ini mendukung tiga nilai faktor bentuk eksplisit: DESKTOP
, PHONE
, dan TABLET
. Selain origin atau URL, tentukan salah satu nilai ini di isi permintaan untuk membatasi hasil hanya untuk pengalaman pengguna tersebut. Contoh ini menunjukkan cara membuat kueri API berdasarkan faktor bentuk menggunakan cURL.
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"}'
Untuk membuat kueri data khusus faktor bentuk ke CrUX API menggunakan JavaScript, panggil fungsi CrUXApiUtil.query
menggunakan parameter url
dan formFactor
dalam isi permintaan.
CrUXApiUtil.query({
url: 'https://web.dev/fast/',
formFactor: 'PHONE'
}).then(response => {
console.log(response);
}).catch(response => {
console.error(response);
});
Menghapus parameter formFactor
sama dengan meminta data untuk semua faktor bentuk yang digabungkan.
{
"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
}
},
// ...
}
}
}
Kolom key
pada respons akan melakukan echo kembali ke konfigurasi permintaan formFactor
untuk mengonfirmasi bahwa hanya pengalaman ponsel yang disertakan.
Ingat kembali dari bagian sebelumnya bahwa 85% pengalaman pengguna di halaman ini memiliki "baik" LCP. Bandingkan dengan pengalaman khusus ponsel, dan hanya 78% yang dianggap "baik". Persentil ke-75 juga lebih lambat di antara pengalaman ponsel, naik dari 1.947 milidetik menjadi 2.366 milidetik. Segmentasi menurut faktor bentuk berpotensi menyoroti perbedaan yang lebih ekstrem dalam pengalaman pengguna.
Menilai performa Core Web Vitals
Program Data Web Inti menentukan target yang membantu menentukan apakah pengalaman pengguna atau distribusi pengalaman dapat dianggap "baik". Pada contoh berikut, kami menggunakan CrUX API dan fungsi CrUXApiUtil.query
untuk menilai apakah distribusi metrik Core Web Vitals (LCP, INP, CLS) halaman web "baik".
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',
'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}).`)
});
}
Hasilnya menunjukkan bahwa halaman ini lulus penilaian Core Web Vitals untuk ketiga metrik.
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).
Dikombinasikan dengan cara otomatis untuk memantau hasil API, data dari CrUX dapat digunakan untuk memastikan pengalaman pengguna nyata menjadi cepat dan tetap cepat. Untuk informasi selengkapnya tentang Core Web Vitals dan cara mengukurnya, lihat Data Web dan Alat untuk mengukur Core Web Vitals.
Apa langkah selanjutnya?
Fitur yang disertakan dalam versi awal CrUX API hanya sebagian kecil dari jenis insight yang dimungkinkan dengan CrUX. Pengguna set data CrUX di BigQuery mungkin sudah mengenal beberapa fitur lanjutan lainnya, termasuk:
- Metrik tambahan
first_paint
dom_content_loaded
onload
time_to_first_byte
notification_permissions
- Dimensi tambahan
month
country
effective connection type
(ECT)
- Perincian tambahan
- histogram yang mendetail
- persentil lebih banyak
Baca dokumen CrUX API resmi untuk mendapatkan kunci API dan mempelajari berbagai contoh aplikasi lainnya. Kami harap Anda mencobanya dan kami ingin mendengar pertanyaan atau masukan apa pun yang mungkin Anda miliki, jadi hubungi kami di forum diskusi CrUX. Untuk terus mendapatkan info terbaru tentang segala hal yang telah kami rencanakan untuk CrUX API, berlanggananlah ke forum pengumuman CrUX atau ikuti kami di Twitter di @ChromeUXReport.