Dipublikasikan: 7 Februari 2023, Terakhir diperbarui: 11 April 2025
Panduan ini memperkenalkan endpoint Chrome UX Report (CrUX) History API, yang menyediakan deret waktu data performa web. Data ini diperbarui setiap minggu, dan memungkinkan Anda melihat histori selama sekitar 6 bulan, dengan 40 titik data yang berjarak satu minggu.
Jika digunakan dengan update harian dari endpoint CrUX API asli, Anda kini dapat dengan cepat melihat data terbaru dan apa yang terjadi sebelumnya, sehingga menjadikannya alat yang efektif untuk melihat perubahan halaman web dari waktu ke waktu.
Mencoba API di halaman ini
Membuat kueri CrUX API harian
Untuk meringkas dari artikel sebelumnya tentang CrUX API, Anda bisa mendapatkan ringkasan data kolom untuk origin tertentu dengan cara ini:
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"}'
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [{
"start": 0, "end": 2500, "density": 0.9192
}, {
"start": 2500, "end": 4000, "density": 0.0513
}, {
"start": 4000, "density": 0.0294
}],
"percentiles": {
"p75": 1303
}
}
// ...
},
"collectionPeriod": {
"firstDate": { "year": 2022, "month": 12, "day": 27 },
"lastDate": { "year": 2023, "month": 1, "day": 23 }
}
}
}
Ringkasan ini mencakup nilai kepadatan histogram dan nilai persentil untuk periode pengumpulan 28 hari tertentu, dalam hal ini, dari 27 Desember 2022 hingga 23 Januari 2023.
Membuat kueri CrUX History API
Untuk memanggil endpoint histori, ubah queryRecord di URL menjadi queryHistoryRecord dalam perintah curl. Menggunakan kunci API CrUX yang sama seperti untuk panggilan sebelumnya akan berhasil.
collectionPeriodCount menentukan jumlah entri deret waktu yang akan ditampilkan; maksimumnya adalah 40. Jika tidak ditentukan, nilai defaultnya adalah 25.
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"origin": "https://web.dev", "collectionPeriodCount": 40}'
Bentuk keseluruhan respons serupa—tetapi ada lebih banyak data. Daripada satu titik data, kini ada deret waktu untuk kolom yang berisi nilai persentil ke-75 (p75) dan kepadatan histogram.
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogramTimeseries": [{
"start": 0, "end": 2500, "densities": [
0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187
]
}, {
"start": 2500, "end": 4000, "densities": [
0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527
]
}, {
"start": 4000, "densities": [
0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285
]
}
],
"percentilesTimeseries": {
"p75s": [
1362, 1352, 1344, 1356, 1366, 1377
]
}
}
// ...
},
"collectionPeriods": [{
"firstDate": { "year": 2022, "month": 7, "day": 10 },
"lastDate": { "year": 2022, "month": 8, "day": 6 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 17 },
"lastDate": { "year": 2022, "month": 8, "day": 13 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 24 },
"lastDate": { "year": 2022, "month": 8, "day": 20 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 31 },
"lastDate": { "year": 2022, "month": 8, "day": 27 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 7 },
"lastDate": { "year": 2022, "month": 9, "day": 3 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 14 },
"lastDate": { "year": 2022, "month": 9, "day": 10 }
}
]
}
}
Dalam contoh ini, deret waktu densities untuk bucket 0 hingga 2.500 md dari metrik Largest Contentful Paint (LCP) adalah [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. Setiap kepadatan ini diamati selama entri collectionPeriods yang sesuai. Misalnya, kepadatan kelima, 0,9183, adalah kepadatan untuk periode pengumpulan kelima, yang berakhir pada 3 September 2022, dan 0,9187 adalah kepadatan pada periode yang berakhir pada minggu setelahnya.
Dengan kata lain, saat menafsirkan entri deret waktu terakhir dalam contoh untuk https://web.dev, ditemukan bahwa dari 14 Agustus 2022 hingga 10 September 2022, 91,87% pemuatan halaman memiliki nilai LCP yang lebih kecil dari 2.500 md, 5,27% memiliki nilai antara 2.500 md dan 4.000 md, dan 2,85% memiliki nilai yang lebih besar dari 4.000 md.
Demikian pula, ada deret waktu untuk nilai p75: LCP p75 untuk 14 Agustus 2022 hingga 10 September 2022 adalah 1377. Artinya, untuk periode pengumpulan ini, 75% pengalaman pengguna memiliki LCP kurang dari 1.377 md, dan 25% pengalaman pengguna memiliki LCP lebih dari 1.377 md.
Meskipun contoh hanya mencantumkan 6 entri deret waktu dan periode pengumpulan, respons dari API menyediakan 25 entri deret waktu secara default dan maksimum 40 - jika "collectionPeriodCount": 40 ditentukan dalam permintaan. Karena tanggal akhir untuk setiap periode pengumpulan ini adalah hari Sabtu yang berjarak 7 hari, dengan "collectionPeriodCount": 40 ini mencakup 10 bulan.
Dalam respons tertentu, panjang deret waktu untuk kepadatan bin histogram dan untuk nilai p75 akan sama persis dengan panjang array di kolom collectionPeriods: Ada korespondensi satu-ke-satu berdasarkan indeks ke dalam array ini.
Mengkueri data tingkat halaman
Selain data tingkat asal, CrUX History API memungkinkan akses ke data tingkat halaman historis. Meskipun data tingkat asal sebelumnya tersedia menggunakan set data CrUX di BigQuery, data historis tingkat halaman hanya tersedia jika situs mengumpulkan dan menyimpan data tersebut sendiri. API baru kini membuka data tingkat halaman historis tersebut.
Data tingkat halaman dapat dikueri dengan cara yang sama, tetapi menggunakan url, bukan origin dalam payload:
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url": "https://web.dev/blog/"}'
Data historis tingkat halaman (dan tingkat asal) tunduk pada persyaratan kelayakan yang sama dengan CrUX lainnya, sehingga halaman tertentu mungkin tidak memiliki catatan historis yang lengkap. Dalam kasus ini, data "yang tidak ada" akan diwakili oleh "NaN" untuk kepadatan histogramTimeseries dan null untuk percentilesTimeseries. Alasan perbedaannya adalah kepadatan histogram selalu berupa angka, sedangkan persentil dapat berupa angka atau string (CLS menggunakan string, meskipun terlihat seperti angka).
Memvisualisasikan data
Cara termudah untuk memvisualisasikan data adalah melalui CrUX Vis, alat yang dibuat khusus untuk mendemonstrasikan keunggulan CrUX History API. Baca selengkapnya di dokumentasi CrUX Vis.
Untuk membuat sendiri diagram serupa, kami telah membuat contoh Colab. Colab, atau 'Colaboratory', memungkinkan Anda menulis dan mengeksekusi Python dari dalam browser. CrUX History API Colab (sumber) menggunakan Python untuk melakukan panggilan ke API dan memetakan data.
Colab ini memungkinkan Anda membuat diagram p75, diagram tiga bin, mendapatkan data dalam bentuk tabel, dan melihat pasangan permintaan dan respons untuk CrUX API, dengan mengisi formulir singkat. Anda tidak perlu menjadi pemrogram untuk menggunakan ini—tetapi Anda tentu dapat melihat kode Python dan mengubahnya menjadi sesuatu yang luar biasa. Nikmati dan jangan ragu untuk memberikan masukan tentang apa yang Anda temukan.
Tentu saja Anda tidak terbatas pada Colab atau Python dan ini hanyalah salah satu contoh cara menggunakan API baru ini. Sebagai endpoint HTTP berbasis JSON, API ini dapat dikueri dari teknologi apa pun.
Kesimpulan
Sebelum diperkenalkannya endpoint CrUX History API, pemilik situs memiliki keterbatasan dalam informasi historis yang dapat mereka peroleh dari CrUX. Data tingkat asal bulanan tersedia menggunakan BigQuery, tetapi data mingguan dan data historis tingkat halaman tidak tersedia. Pemilik situs dapat merekam data ini sendiri menggunakan API harian, tetapi sering kali kebutuhan ini baru diketahui setelah terjadi regresi dalam metrik.
Dengan diperkenalkannya CrUX History API ini, diharapkan pemilik situs dapat lebih memahami perubahan metrik situs mereka, dan sebagai alat diagnostik saat masalah muncul. Jika Anda menggunakan API baru, masukan dapat disampaikan di grup Google Chrome UX Report (Diskusi).
Ucapan terima kasih
Gambar banner oleh Dave Herring di Unsplash