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.
Saat 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 andal untuk melihat perubahan halaman web dari waktu ke waktu.
Mengkueri 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 }
}
}
}
Snapshot 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.
Mengkueri 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. Alih-alih 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 pada periode yang berakhir minggu setelah itu.
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 memiliki nilai antara 2.500 md dan 4.000 md, dan 5,27% memiliki nilai antara 2.500 md dan 4.000 md, dan
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 milidetik, dan 25% pengalaman pengguna memiliki LCP lebih besar dari 1.377 milidetik.
Sementara contoh ini 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 terpisah 7 hari, ini mencakup 6 bulan.
Dalam respons tertentu, panjang deret waktu untuk kepadatan bin histogram dan nilai p75 akan sama persis dengan panjang array di kolom collectionPeriods: Ada korespondensi one-to-one berdasarkan indeks ke dalam array ini.
Membuat kueri data tingkat halaman
Selain data tingkat origin, CrUX History API memungkinkan akses ke data tingkat halaman historis. Meskipun data tingkat asal tersedia sebelumnya 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, "hilang" data akan ditampilkan oleh "NaN" untuk kepadatan histogramTimeseries dan null untuk percentilesTimeseries. Alasan perbedaannya adalah kepadatan histogram selalu berupa angka, sedangkan persentil bisa 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 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 termasuk dalam rentang tertentu untuk metrik INP, yang ditampilkan melalui diagram batang bertumpuk. Diagram p75 memberikan ringkasan singkat, dan dalam satu diagram, cukup mudah untuk menambahkan beberapa metrik, atau menampilkan garis untuk PHONE dan DESKTOP. Diagram tri-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 sendiri diagram tersebut, 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 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 seorang {i>programmer<i} untuk menggunakan ini—tetapi Anda pasti dapat melihat kode Python dan memodifikasinya menjadi sesuatu yang menakjubkan! 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 satu contoh cara menggunakan API baru ini. Sebagai endpoint HTTP berbasis JSON, API dapat dikueri dari teknologi apa pun.
Kesimpulan
Sebelum diperkenalkannya endpoint CrUX History API, informasi historis yang dapat diperoleh dari CrUX dibatasi oleh pemilik situs. Data tingkat asal bulanan tersedia menggunakan BigQuery dan Dasbor CrUX, tetapi data mingguan tidak tersedia, begitu juga dengan data historis tingkat halaman. Pemilik situs dapat merekam sendiri data ini menggunakan API harian, tetapi sering kali kebutuhan akan data ini hanya ditemukan setelah terjadi regresi dalam metrik.
Diharapkan dengan diperkenalkannya CrUX History API ini, pemilik situs dapat lebih memahami perubahan metrik situs mereka dan berfungsi sebagai alat diagnostik saat terjadi masalah. Jika Anda menggunakan API baru ini, kami akan menerima masukan di grup google Laporan UX Chrome (Diskusi).
Ucapan terima kasih
Banner besar oleh Dave Herring di Unsplash