CrUX History API memberikan akses latensi rendah ke data pengalaman pengguna nyata historis selama enam bulan di tingkat perincian halaman dan asal.
Kasus penggunaan umum
CrUX History API memungkinkan kueri metrik pengalaman pengguna historis untuk URI tertentu seperti "Dapatkan tren UX historis untuk asal https://example.com
".
History API mengikuti struktur yang sama dengan CrUX API harian, kecuali nilainya diberikan dalam array, dan kunci diberi label dengan nama jamak (misalnya, histogramTimeseries
bukan histogram
, atau p75s
bukan p75
).
Kunci API CrUX
Seperti API harian, penggunaan CrUX History API memerlukan kunci Google Cloud API. Kunci yang sama dapat digunakan untuk API harian dan histori.
Anda dapat membuatnya di halaman Credentials dan menyediakannya untuk penggunaan Chrome UX Report API
.
Setelah Anda memiliki kunci API, aplikasi Anda dapat menambahkan parameter kueri key=[YOUR_API_KEY]
ke semua URL permintaan. Lihat Contoh kueri.
Kunci API aman untuk disematkan dalam URL; tidak memerlukan encoding apa pun.
Model data
Bagian ini menjelaskan struktur data dalam permintaan dan respons.
Record
Informasi terpisah tentang halaman atau situs. Kumpulan data dapat memiliki data yang spesifik untuk ID dan untuk kombinasi dimensi tertentu. Kumpulan data dapat berisi data untuk satu atau beberapa metrik.
ID
ID menentukan data yang harus dicari. Dalam CrUX, ID ini adalah halaman web dan situs.
Origin
Jika ID adalah origin, semua data yang ada untuk semua halaman dalam origin tersebut akan digabungkan. Misalnya, misalkan http://www.example.com
origin memiliki halaman seperti yang diatur oleh peta situs ini:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Artinya, saat mengkueri Laporan UX Chrome dengan origin yang ditetapkan ke http://www.example.com
, data untuk http://www.example.com/
, http://www.example.com/foo.html
, dan http://www.example.com/bar.html
akan ditampilkan, yang digabungkan bersama, karena semuanya adalah halaman dalam asal tersebut.
URL
Jika ID adalah URL, hanya data untuk URL spesifik tersebut yang akan ditampilkan. Mencari kembali peta situs asal http://www.example.com
:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Jika ID ditetapkan ke URL dengan nilai http://www.example.com/foo.html
, hanya data untuk halaman tersebut yang akan ditampilkan.
Dimensi
Dimensi mengidentifikasi grup data tertentu yang digabungkan dengan kumpulan data. Misalnya, faktor bentuk PHONE
menunjukkan bahwa data berisi informasi tentang pemuatan yang terjadi di perangkat seluler.
CrUX History API hanya tersedia dalam kondisi teragregasi berdasarkan dimensi faktor bentuk. Ini adalah class umum perangkat yang dibagi menjadi PHONE
, TABLET
, dan DESKTOP
.
Metrik
Kami melaporkan metrik dalam deret waktu agregasi statistik, yang berupa histogram, persentil, dan fraksi.
Histogram
Jika metrik dinyatakan dalam array histogram, setiap entri deret waktu mewakili persentase pemuatan halaman yang metriknya jatuh ke dalam interval, secara proporsional terhadap semua. Titik data disajikan dalam urutan tanggal periode pengumpulan yang juga ditampilkan oleh API, dengan titik pertama adalah periode paling awal, dan titik terakhir adalah periode pengumpulan terbaru.
Histogram tiga bin sederhana untuk contoh metrik terlihat seperti ini:
{
"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]
}
],
}
Data ini menunjukkan bahwa 91,90% pemuatan halaman mengalami contoh nilai metrik antara 0 md dan 2.500 md untuk periode pengumpulan pertama dalam histori, diikuti oleh 92,03%, 91,94%... Satuan metrik tidak terdapat dalam histogram ini, dalam hal ini kami akan mengasumsikan milidetik.
Selain itu, 5,21% pemuatan halaman mengalami contoh nilai metrik antara 2.500 md hingga 4.000 md pada periode pengumpulan pertama dalam histori, dan 2,88% pemuatan halaman mengalami nilai lebih besar dari 4.000 md pada periode pengumpulan pertama dalam histori.
Persentil
Metrik juga dapat berisi deret waktu persentil yang dapat berguna untuk analisis tambahan.
Titik data disajikan dalam urutan tanggal periode pengumpulan yang juga ditampilkan oleh API, dengan titik pertama adalah periode paling awal, dan titik terakhir adalah periode pengumpulan terbaru.
{
"percentilesTimeseries": {
"p75s": [1362, 1352, 1344, 1356, 1366, 1377]
},
}
Persentil ini dapat menampilkan nilai metrik tertentu pada persentil yang ditentukan untuk metrik tersebut. Tabel sementara didasarkan pada set lengkap data yang tersedia dan bukan data yang digabungkan akhir, sehingga tidak selalu cocok dengan persentil terinterpolasi yang didasarkan pada histogram kelompok akhir.
Pecahan
Metrik dapat dinyatakan sebagai deret waktu untuk pecahan berlabel; setiap label menjelaskan pemuatan halaman dengan cara tertentu. Titik data disajikan dalam urutan tanggal periode pengumpulan yang juga ditampilkan oleh API, dengan titik pertama adalah periode paling awal, dan titik terakhir adalah periode pengumpulan terbaru.
Contoh:
{
"fractionTimeseries": {
"desktop": {"fractions": [0.3195, 0.2115, 0.1421]},
"phone": {"fractions": [0.6295, 0.7544, 0.8288]},
"tablet": {"fractions": [0.051, 0.0341, 0.029]}
}
}
Dalam contoh ini, titik data terbaru menunjukkan 14,21% pemuatan halaman berasal dari desktop, dan 82,88% berasal dari ponsel.
Jenis nilai metrik
Karena CrUX History API menggunakan jenis nilai metrik yang sama, Anda dapat melihat dokumentasi jenis nilai metrik CrUX API harian untuk mengetahui detail selengkapnya.
Kelayakan metrik
Berdasarkan kriteria kelayakan, origin atau URL mungkin hanya memenuhi syarat untuk beberapa periode pengumpulan yang dicakup oleh CrUX History API. Dalam kasus ini, CrUX History API akan menampilkan "NaN"
untuk kepadatan histogramTimeseries
dan null
untuk percentilesTimeseries
untuk periode pengumpulan yang tidak memiliki data yang memenuhi syarat. Alasan perbedaannya adalah kepadatan histogram selalu berupa angka, sedangkan persentil dapat berupa angka atau string (CLS menggunakan string, meskipun terlihat seperti angka).
Misalnya, jika periode kedua tidak memiliki data yang memenuhi syarat, hal ini akan ditampilkan sebagai:
{
"histogramTimeseries": [
{
"start": 0,
"end": 2500,
"densities": [0.9190, "NaN", 0.9194, 0.9195, 0.9183, 0.9187]
},
{
"start": 2500,
"end": 4000,
"densities": [0.0521, "NaN", 0.0518, 0.0518, 0.0526, 0.0527]
},
{
"start": 4000,
"densities": [0.0288, "NaN", 0.0286, 0.0285, 0.0290, 0.0285]
}
],
"percentilesTimeseries": {
"p75s": [1362, null, 1344, 1356, 1366, 1377]
},
}
Untuk URL atau asal yang termasuk dan tidak memenuhi syarat dari waktu ke waktu, Anda mungkin akan melihat banyak entri yang tidak ada.
Periode pengumpulan
CrUX History API berisi objek collectionPeriods
dengan array kolom firstDate
dan endDate
yang mewakili tanggal mulai dan akhir dari setiap periode agregasi. Contoh:
"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 }
}
]
Periode pengumpulan ini diurutkan dalam urutan menaik dan mewakili rentang tanggal setiap titik data di bagian respons yang lain.
History API diupdate setiap hari Senin dan berisi data hingga hari Sabtu sebelumnya (sesuai dengan jeda 2 hari standar). {i>Dataset<i} ini berisi data selama 25 minggu sebelumnya—satu periode pengumpulan per minggu.
Karena setiap periode pengumpulan berisi data gabungan 28 hari sebelumnya, dan periode pengumpulannya adalah per minggu, artinya periode pengumpulan akan tumpang-tindih. Angka-angka ini mirip dengan data rata-rata bergerak, dengan data selama tiga minggu disertakan dalam setiap periode berikutnya, dan satu minggu berbeda.
Contoh kueri
Kueri dikirim sebagai objek JSON menggunakan permintaan POST ke https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]"
dengan data kueri sebagai objek JSON dalam isi POST.
Perhatikan penggunaan queryHistoryRecord
yang menggantikan queryRecord
CrUX API harian.
Contoh isi adalah:
{
"origin": "https://example.com",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Misalnya, kode ini dapat dipanggil dari curl
dengan command line berikut (menggantikan API_KEY
dengan kunci Anda):
curl -s --request POST 'https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"formFactor":"PHONE","origin":"https://www.example.com","metrics":["largest_contentful_paint", "experimental_time_to_first_byte"]}'
Data tingkat halaman tersedia melalui API dengan meneruskan properti url
dalam kueri, bukan origin
:
{
"url": "https://example.com/page",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Jika properti metrics
tidak ditetapkan, semua metrik yang tersedia akan ditampilkan:
cumulative_layout_shift
first_contentful_paint
first_input_delay
interaction_to_next_paint
largest_contentful_paint
experimental_time_to_first_byte
navigation_types
form_factors
(hanya dilaporkan jika tidak adaformFactor
yang ditentukan dalam permintaan)
Jika tidak ada nilai formFactor
yang diberikan, nilai akan digabungkan di semua faktor bentuk.
Lihat panduan Menggunakan CrUX History API untuk contoh kueri lainnya.
Pipeline data
Set data CrUX diproses melalui pipeline untuk menggabungkan, menggabungkan, dan memfilter data sebelum tersedia melalui API.
Rata-rata penggiliran
Data dalam Laporan UX Chrome adalah rata-rata penggiliran 28 hari dari metrik gabungan. Artinya, data yang ditampilkan di Laporan UX Chrome pada waktu tertentu sebenarnya adalah data selama 28 hari terakhir yang digabungkan bersama.
History API berisi sejumlah periode pengumpulan, masing-masing mencakup periode 28 hari tersebut. Karena setiap periode pengumpulan berisi data gabungan 28 hari sebelumnya, dan periode pengumpulannya adalah per minggu, artinya periode pengumpulan akan tumpang-tindih. Angka-angka ini mirip dengan data rata-rata bergerak, dengan data selama tiga minggu disertakan dalam setiap periode berikutnya, dan satu minggu berbeda.
Info terbaru mingguan
History API diperbarui setiap hari Senin sekitar pukul 04.00 UTC dan berisi data hingga hari Sabtu sebelumnya (sesuai dengan jeda 2 hari standar). {i>Dataset<i} ini berisi data selama 25 minggu sebelumnya (sekitar 6 bulan), satu periode pengumpulan per minggu.
Tidak ada perjanjian tingkat layanan untuk waktu update. Proses ini dijalankan dengan upaya terbaik setiap hari.
Skema
Ada satu endpoint untuk CrUX History API yang menerima permintaan HTTP POST
. API menampilkan record
yang berisi satu atau beberapa metrics
yang sesuai dengan data performa tentang asal atau halaman yang diminta.
Permintaan HTTP
POST https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord
URL menggunakan sintaksis gRPC Transcoding.
Isi permintaan
CrUX History API menggunakan isi permintaan yang sama seperti CruUX API harian, kecuali tidak mendukung kolom permintaan effectiveConnectionType
.
Misalnya, untuk meminta nilai Largest Contentful Paint di desktop untuk halaman beranda web.dev:
{
"origin": "https://web.dev/",
"formFactor": "DESKTOP",
"metrics": [
"largest_contentful_paint"
]
}
Isi respons
Permintaan yang berhasil akan menampilkan respons dengan objek record
dan urlNormalizationDetails
dalam struktur berikut:
{
"record": {
"key": {
object (Key)
},
"metrics": [
string: {
object (Metric)
}
]
},
"urlNormalizationDetails": {
object (UrlNormalization)
}
}
Misalnya, respons terhadap isi permintaan dalam permintaan sebelumnya dapat berupa:
{
"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 }
}, {
...
}
]
}
}
Kunci
Key
menentukan semua dimensi yang mengidentifikasi data ini sebagai unik.
{
"formFactor": enum (FormFactor),
// Union field url_pattern can be only one of the following:
"origin": string,
"url": string
// End of list of possible types for union field url_pattern.
}
Kolom | |
---|---|
formFactor |
Faktor bentuk adalah class perangkat yang digunakan semua pengguna untuk mengakses situs untuk data ini. Jika faktor bentuk tidak ditentukan, data gabungan atas semua faktor bentuk akan ditampilkan. |
Kolom union url_ . Pola URL adalah URL tempat data akan diterapkan. url_ hanya ada berupa salah satu diantara berikut: |
|
origin |
Origin menentukan origin yang akan digunakan data ini. Catatan: Saat menentukan origin, data untuk pemuatan berdasarkan origin ini pada semua halaman akan digabungkan ke dalam data pengalaman pengguna tingkat origin. |
url |
Catatan: Saat menentukan |
Metrik
metric
adalah kumpulan data pengalaman pengguna untuk metrik performa web tunggal, seperti first contentful paint. File ini berisi histogram ringkasan penggunaan Chrome di dunia nyata sebagai rangkaian bins
.
{
"histogramTimeseries": [
{
object (Bin)
}
],
"percentilesTimeseries": {
object (Percentiles)
}
}
atau
"fractionTimeseries": {
object (Fractions)
}
Kolom | |
---|---|
histogramTimeseries[] |
Histogram deret waktu tentang pengalaman pengguna untuk metrik. Histogram deret waktu akan memiliki setidaknya satu bin dan kepadatan semua bin akan berjumlah ~1. Nilai yang hilang untuk Periode Pengumpulan tertentu akan ditandai sebagai |
percentilesTimeseries |
Persentil umum yang berguna dari Metrik. Jenis nilai untuk persentil akan sama dengan jenis nilai yang diberikan untuk kelompok Histogram. Nilai yang hilang untuk Periode Pengumpulan tertentu akan ditandai sebagai |
fractionTimeseries |
Objek ini berisi deret waktu dari pecahan berlabel, yang berjumlah ~1 per entri. Pecahan dibulatkan menjadi 4 angka di belakang koma. Entri yang hilang dinyatakan sebagai `"NaN"` di seluruh pecahan. |
Bin
bin
adalah bagian data terpisah yang mencakup dari awal hingga akhir, atau jika tidak ada akhir yang diberikan dari awal hingga tak terhingga positif.
Nilai awal dan akhir kotak diberikan dalam jenis nilai metrik yang diwakilinya. Misalnya, first contentful paint diukur dalam milidetik dan ditampilkan sebagai int, sehingga kelompok metriknya akan menggunakan int32 untuk jenis awal dan akhirnya. Namun, pergeseran tata letak kumulatif diukur dalam desimal tanpa unit dan ditampilkan sebagai desimal yang dienkode sebagai string sehingga kelompok metriknya akan menggunakan string untuk jenis nilainya.
{
"start": value,
"end": value,
"densities": [number, number, number...etc.]
}
Kolom | |
---|---|
start |
{i>Start<i} adalah awal dari {i>data bin<i}. |
end |
{i>End<i} adalah akhir dari {i>data bin<i}. Jika end tidak terisi, tempat tidak memiliki akhir dan valid dari awal hingga +inf. |
densities |
Deret waktu proporsi pengguna yang mengalami nilai kelompok ini untuk metrik yang ditentukan. Kepadatan dibulatkan menjadi 4 angka desimal. |
Persentil
Percentiles
berisi nilai sintetis metrik pada persentil statistik tertentu. Ini digunakan untuk memperkirakan nilai metrik seperti yang dialami oleh sebagian persentase pengguna dari total jumlah pengguna.
{
"P75": value
}
Kolom | |
---|---|
p75s |
Deret waktu nilai yang 75% pemuatan halaman mengalami metrik yang ditentukan pada atau kurang dari nilai ini. |
Pecahan
Fractions
berisi deret waktu dari pecahan berlabel yang berjumlah ~1, per entri.
Setiap label menggambarkan pemuatan halaman, sehingga metrik yang ditunjukkan dengan cara ini
dapat dianggap sebagai menghasilkan nilai yang berbeda, bukan nilai numerik, dan
pecahan menunjukkan seberapa sering nilai yang berbeda diukur.
{
"label_1": { "fractions": array[fraction]},
"label_1": { "fractions": array[fraction]},
...
"label_n": { "fractions": array[fraction]}
}
Mirip dengan nilai kepadatan dalam kumpulan histogram, setiap fraction
adalah angka
0.0 <= value <= 1.0
, dan jumlahnya mencapai ~1,0. Jika metrik tidak tersedia untuk periode pengumpulan tertentu, entri yang sesuai akan menjadi "NaN" di semua array fraksi.
Kolom | |
---|---|
p75s |
Deret waktu nilai yang 75% pemuatan halaman mengalami metrik yang ditentukan pada atau lebih rendah dari nilai ini. |
UrlNormalization
Objek yang menunjukkan tindakan normalisasi yang dilakukan untuk menormalisasi URL agar memiliki peluang yang lebih tinggi untuk keberhasilan pencarian. Perubahan ini adalah perubahan otomatis sederhana yang diambil ketika mencari url_pattern
yang disediakan akan dianggap gagal. Tindakan kompleks seperti pengalihan berikut tidak ditangani.
{
"originalUrl": string,
"normalizedUrl": string
}
Kolom | |
---|---|
originalUrl |
URL asli yang diminta sebelum tindakan normalisasi. |
normalizedUrl |
URL setelah tindakan normalisasi. Ini adalah URL pengalaman pengguna yang valid yang dapat dicari secara wajar. |
Batas kapasitas
CrUX History API memiliki batas yang sama dengan CrUX API untuk 150 kueri per menit per project Google Cloud untuk kedua API tersebut, yang ditawarkan tanpa biaya. Batas ini, dan penggunaan Anda saat ini, dapat dilihat di Google Cloud Console. Kuota yang besar ini seharusnya cukup untuk sebagian besar kasus penggunaan dan tidak mungkin untuk membayar peningkatan kuota.