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 seminggu.
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
Sebagai ringkasan dari artikel sebelumnya tentang CrUX API, Anda bisa mendapatkan ringkasan data kolom untuk asal 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. Anda dapat menggunakan kunci API CrUX yang sama dengan panggilan sebelumnya.
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 terdapat 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 2500 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: 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 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 akses ke 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 seperti CrUX lainnya, sehingga halaman khususnya 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. 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? Ditemukan bahwa cara ini mempermudah pemetaan 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 cepat, dan dalam satu diagram, relatif mudah untuk 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. Pada kedua diagram, relatif mudah untuk menyimpulkan bahwa ada regresi performa yang dimulai pada akhir Oktober, dan telah 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.
Colab ini memungkinkan Anda membuat diagram p75, diagram tri-bin, mendapatkan data dalam bentuk tabel, serta 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, informasi historis yang dapat diperoleh dari CrUX dibatasi oleh pemilik situs. 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 pemilik situs dapat memiliki pemahaman yang lebih baik tentang metrik situs 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