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 25 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 ini menjadi alat yang efektif untuk melihat perubahan halaman web dari waktu ke waktu.
Coba API di halaman ini
Membuat kueri CrUX API harian
Untuk merangkum 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 di perintah curl. Menggunakan kunci API CrUX yang sama seperti untuk panggilan sebelumnya akan berfungsi.
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"}'
Bentuk respons secara keseluruhan 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 dalam periode yang berakhir seminggu setelahnya.
Dengan kata lain, dengan 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 lebih besar dari 4.000 md.
Demikian pula, ada deret waktu untuk nilai p75: p75 LCP 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 memberikan 25 entri deret waktu; karena tanggal akhir untuk setiap periode pengumpulan ini adalah hari Sabtu yang berjarak 7 hari, periode ini mencakup 6 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 array ini.
Membuat kueri data tingkat halaman
Selain data tingkat origin, CrUX History API memungkinkan akses ke data historis tingkat halaman. Meskipun data tingkat origin sebelumnya tersedia menggunakan set data CrUX di BigQuery (atau menggunakan Dasbor CrUX), data historis tingkat halaman hanya tersedia jika situs mengumpulkan dan menyimpan data itu sendiri. API baru kini membuka data historis tingkat halaman 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 origin) tunduk pada persyaratan kelayakan yang sama seperti data lainnya di CrUX, sehingga halaman tertentu mungkin tidak memiliki data historis yang lengkap. Dalam hal ini, data "yang tidak ada" akan direpresentasikan oleh "NaN" untuk kepadatan histogramTimeseries dan null untuk percentilesTimeseries. Penyebab perbedaannya adalah kepadatan histogram selalu berupa angka, sedangkan persentil dapat berupa angka atau string (CLS menggunakan string, meskipun terlihat seperti angka).
Memvisualisasikan data
Jadi, Anda mungkin bertanya, mengapa data dibentuk dengan cara ini? Hal ini ditemukan bahwa hal ini mempermudah plot grafik. Misalnya, berikut adalah grafik untuk nilai p75 untuk Interaction To Next Paint (INP) untuk https://web.dev:
Dalam diagram garis ini, setiap nilai pada sumbu y adalah nilai p75 dari deret waktu p75s, dan sumbu x adalah waktu, yang disiapkan sebagai lastDate untuk setiap periode pengumpulan.
Berikut adalah grafik untuk deret waktu bin histogram—dikenal sebagai diagram tri-bin—karena histogram ini memiliki tiga bin.
Sumbu x disiapkan sebagai lastDate untuk setiap periode pengumpulan. Namun, kali ini, sumbu y adalah persentase pemuatan halaman yang berada dalam rentang tertentu untuk metrik INP, yang ditampilkan melalui diagram batang bertumpuk. Diagram p75 memberikan ringkasan singkat, dan dalam satu diagram, Anda dapat dengan mudah menambahkan beberapa metrik, atau menampilkan garis untuk PHONE dan DESKTOP. Diagram tiga bin memberikan gambaran tentang distribusi nilai metrik yang diukur selama setiap periode pengumpulan.
Misalnya, meskipun diagram p75 menunjukkan bahwa https://web.dev memiliki nilai INP yang hampir dapat diterima selama periode pengamatan, diagram tri-bin menunjukkan bahwa untuk sebagian kecil pemuatan halaman, INP sebenarnya buruk. Dalam kedua diagram, relatif mudah untuk menyimpulkan bahwa ada regresi performa yang dimulai menjelang akhir Oktober, dan diperbaiki pada pertengahan November.
Untuk membuat diagram tersebut sendiri, kami telah membuat contoh Colab. Colab, atau 'Colaboratory', memungkinkan Anda menulis dan mengeksekusi Python dari dalam browser. Colab CrUX History API (sumber) menggunakan Python untuk melakukan panggilan ke API dan membuat diagram data.
Dengan Colab ini, Anda dapat membuat diagram p75, diagram tri-bin, mendapatkan data dalam bentuk tabel, dan melihat pasangan permintaan dan respons untuk CrUX API, dengan mengisi formulir singkat. Anda tidak perlu menjadi programmer untuk menggunakannya—tetapi Anda tentu dapat melihat kode Python dan mengubahnya menjadi sesuatu yang luar biasa. Selamat menikmati 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 dapat dikueri dari teknologi apa pun.
Kesimpulan
Sebelum pengenalan endpoint CrUX History API, pemilik situs memiliki keterbatasan informasi historis yang dapat mereka peroleh dari CrUX. Data tingkat origin bulanan tersedia menggunakan BigQuery dan Dasbor CrUX, tetapi data mingguan tidak tersedia, begitu juga data historis tingkat halaman. Pemilik situs dapat merekam data ini sendiri menggunakan API harian, tetapi sering kali kebutuhan untuk hal ini hanya ditemukan setelah terjadi regresi dalam metrik.
Harapan kami dengan diperkenalkannya CrUX History API ini adalah agar pemilik situs dapat lebih memahami metrik situs mereka yang berubah, dan sebagai alat diagnostik saat masalah muncul. Jika Anda menggunakan API baru, kirimkan masukan Anda ke grup Google Chrome UX Report (Discussions).
Ucapan terima kasih
Banner besar oleh Dave Herring di Unsplash