API Histori CrUX

CrUX History API memberikan akses latensi rendah ke data pengalaman pengguna nyata historis selama enam bulan pada perincian halaman dan origin.

Cobalah!

Kasus penggunaan umum

CrUX History API memungkinkan pembuatan kueri metrik pengalaman pengguna historis untuk URI tertentu seperti "Mendapatkan tren UX historis untuk asal https://example.com".

History API mengikuti struktur yang sama dengan CrUX API harian kecuali nilai diberikan dalam array, dan kunci diberi label dengan nama jamak (misalnya, histogramTimeseries dan bukan histogram, atau p75s, bukan p75).

Kunci API CrUX

Seperti API harian, penggunaan CrUX History API memerlukan kunci Google Cloud API yang disediakan untuk penggunaan Chrome UX Report API. Kunci yang sama dapat digunakan untuk API harian dan histori.

Mendapatkan dan menggunakan kunci API

Dapatkan Kunci

Atau buat satu di halaman Credentials.

Setelah Anda memiliki kunci API, aplikasi Anda dapat menambahkan parameter kueri key=yourAPIKey ke semua URL permintaan.

Kunci API aman untuk disematkan dalam URL; dan tidak memerlukan encoding apa pun.

Lihat Contoh kueri.

Model data

Bagian ini menjelaskan struktur data dalam permintaan dan respons.

Rekam

Sepotong 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.

Pengenal

ID menentukan kumpulan data apa yang harus dicari. Di CrUX, pengenal ini adalah halaman web dan situs web.

Asal

Jika ID adalah origin, semua data yang ada untuk semua halaman dalam origin tersebut akan digabungkan. Misalnya, asal http://www.example.com memiliki halaman yang diatur oleh peta situs ini:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Artinya, saat membuat kueri 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, digabungkan bersama, karena semua halaman tersebut merupakan halaman di bawah origin tersebut.

URL

Jika ID-nya adalah URL, hanya data untuk URL spesifik tersebut yang akan ditampilkan. Lihat 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 sedang 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 untuk digabungkan berdasarkan dimensi faktor bentuk. Ini adalah class umum perangkat yang dibagi menjadi PHONE, TABLET, dan DESKTOP.

Catatan: Tidak seperti API harian, CrUX History API tidak memiliki data yang digabungkan berdasarkan Effective Connection Type (ECT).

Metrik

Kami melaporkan metrik dalam deret waktu agregasi statistik, yaitu histogram, persentil, dan pecahan.

Histogram

Bila metrik dinyatakan dalam susunan histogram, maka setiap entri deret waktu akan mewakili persentase pemuatan halaman yang mana metrik tersebut termasuk dalam suatu interval, secara proporsional dengan semua metrik tersebut. 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 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 sejarah, diikuti oleh 92,03%, 91,94%... Unit metrik tidak terdapat dalam histogram ini, dalam hal ini kami akan mengasumsikan bahwa dalam milidetik.

Selain itu, 5,21% pemuatan halaman mengalami nilai metrik contoh antara 2.500 md dan 4.000 md pada periode pengumpulan pertama dalam sejarah, dan 2,88% pemuatan laman mengalami nilai lebih besar dari 4.000 md pada periode pengumpulan pertama dalam sejarah.

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 diberikan untuk metrik tersebut. Mereka didasarkan pada set lengkap data yang tersedia dan bukan data binned akhir, sehingga mereka tidak selalu cocok dengan persentil terinterpolasi yang didasarkan pada histogram binned akhir.

Catatan: Nilai untuk setiap persentil berasal secara sintetis. Hal ini tidak berarti bahwa pengguna benar-benar mengalami nilai yang ditunjukkan, hanya sebagian persentase pengguna yang mengalami nilai metrik yang kurang dari nilai yang diberikan.

Pecahan

Metrik dapat dinyatakan sebagai deret waktu untuk pecahan berlabel; setiap label menjelaskan pemuatan halaman dalam sebelumnya. 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, asal atau URL mungkin hanya memenuhi syarat untuk beberapa periode pengumpulan yang tercakup dalam CrUX History API. Dalam kasus ini, CrUX History API akan menampilkan "NaN" untuk kepadatan histogramTimeseries dan null untuk percentilesTimeseries selama periode pengumpulan tanpa data yang memenuhi syarat. Alasan perbedaannya adalah kepadatan histogram selalu berupa angka, sedangkan persentil bisa berupa angka atau string (CLS menggunakan string, meskipun terlihat seperti angka).

Misalnya, jika periode kedua tidak memiliki data yang memenuhi syarat, 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 origin yang tidak memenuhi syarat seiring waktu, Anda mungkin akan melihat banyak entri yang hilang.

Periode pengumpulan

CrUX History API berisi objek collectionPeriods dengan array kolom firstDate dan endDate yang mewakili tanggal awal dan akhir 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 dalam urutan menaik dan mewakili rentang tanggal setiap titik data di bagian lain dari respons.

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 pengumpulan adalah per minggu, artinya periode pengumpulan akan tumpang tindih. Pergerakan tersebut mirip dengan data pergerakan rata-rata, dengan data selama tiga minggu disertakan dalam setiap periode berikutnya, dan selama 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 (mengganti 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"]}'

Catatan: Contoh sebelumnya adalah untuk sistem berbasis macOS atau Linux—termasuk shell Git BASH untuk Windows. Sistem lain mungkin memerlukan sedikit perubahan. Misalnya, command line cmd.exe tidak mengizinkan tanda kutip tunggal untuk parameter, atau kelanjutan baris (\), sehingga memerlukan penggunaan tanda kutip ganda (menghilangkan tanda kutip dalam yang sesuai dengan \"), dan juga menggunakan satu baris.

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
• round_trip_time
• form_factors (hanya dilaporkan jika tidak ada formFactor yang ditentukan dalam permintaan)

Jika nilai formFactor tidak 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 di Laporan UX Chrome merupakan rata-rata penggiliran 28 hari dari metrik gabungan. Artinya, data yang disajikan di Laporan UX Chrome pada waktu tertentu sebenarnya merupakan data selama 28 hari terakhir yang digabungkan.

History API berisi sejumlah periode pengumpulan, masing-masing mencakup 28 hari ini. Karena setiap periode pengumpulan berisi data gabungan 28 hari sebelumnya, dan periode pengumpulan adalah per minggu, artinya periode pengumpulan akan tumpang tindih. Pergerakan tersebut mirip dengan data pergerakan rata-rata, dengan data selama tiga minggu disertakan dalam setiap periode berikutnya, dan selama satu minggu berbeda.

Info terbaru mingguan

History API diupdate setiap hari Senin sekitar pukul 04.00 UTC dan berisi data hingga hari Sabtu sebelumnya (sesuai jeda 2 hari standar). Paket ini berisi data selama 25 minggu sebelumnya (sekitar 6 bulan), satu periode pengumpulan per minggu.

Tidak ada perjanjian tingkat layanan untuk waktu pembaruan; dan kami berupaya sebaik mungkin setiap hari.

Perhatian: Data tidak akan berbeda dalam minggu yang sama setelah diperbarui setiap hari Senin sekitar pukul 04.00 UTC. Panggilan berulang akan memberikan hasil yang sama.

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 CreUX API harian, kecuali tidak mendukung kolom permintaan effectiveConnectionType.

Misalnya, guna meminta nilai Largest Contentful Paint 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 di 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	enum (FormFactor) Faktor bentuk adalah class perangkat yang digunakan semua pengguna untuk mengakses situs untuk data ini. Jika faktor bentuk tidak ditentukan, data gabungan dari semua faktor bentuk akan ditampilkan.
Kolom union url_pattern. Pola URL adalah URL tempat data diterapkan. url_pattern hanya dapat berupa salah satu dari berikut:
origin	string Origin menentukan origin yang menjadi tujuan kumpulan data ini. Catatan: Saat menentukan origin, data untuk pemuatan pada origin ini di semua halaman akan digabungkan ke dalam data pengalaman pengguna tingkat origin.
url	string url menentukan URL spesifik yang menjadi tujuan data ini. Catatan: Saat menentukan url, hanya data untuk URL spesifik tersebut yang akan digabungkan.

Metrik

metric adalah kumpulan data pengalaman pengguna untuk satu metrik performa web, seperti first contentful paint. Paket ini berisi histogram ringkasan penggunaan Chrome di dunia nyata sebagai rangkaian bins.

{
  "histogramTimeseries": [
    {
      object (Bin)
    }
  ],
  "percentilesTimeseries": {
    object (Percentiles)
  }
}

atau

"fractionTimeseries": {
  object (Fractions)
}

Kolom
histogramTimeseries[]	object (Bin) Histogram deret waktu pengalaman pengguna untuk metrik. Histogram deret waktu akan memiliki setidaknya satu kelompok dan kepadatan semua kelompok akan bertambah hingga ~1. Nilai yang tidak ada untuk Periode Pengumpulan tertentu akan ditandai sebagai "NaN".
percentilesTimeseries	object (Percentiles) Persentil umum berguna dari Metrik. Jenis nilai untuk persentil akan sama dengan jenis nilai yang diberikan untuk bin Histogram. Nilai yang tidak ada untuk Periode Pengumpulan tertentu akan ditandai sebagai null.
fractionTimeseries	object (Fractions) Objek ini berisi deret waktu dari pecahan berlabel, yang berjumlah ~1 per entri. Pecahan dibulatkan ke 4 angka desimal. Entri yang hilang dinyatakan sebagai `"NaN"` di semua pecahan.

Kotak

bin adalah bagian terpisah dari data yang terentang dari awal hingga akhir, atau jika tidak ada akhir yang diberikan dari awal hingga tak terhingga positif.

Nilai awal dan akhir bin diberikan dalam jenis nilai metrik yang diwakilinya. Misalnya, first contentful paint diukur dalam milidetik dan diekspos sebagai int, sehingga kumpulan metriknya akan menggunakan int32 untuk jenis awal dan akhirnya. Namun, pergeseran tata letak kumulatif diukur dalam desimal tanpa unit dan diekspos sebagai desimal yang dienkode sebagai string sehingga bin metriknya akan menggunakan string untuk jenis nilainya.

{
  "start": value,
  "end": value,
  "densities": [number, number, number...etc.]
}

Kolom
start	(integer | string) Awal adalah awal dari bin data.
end	(integer | string) {i>End<i} adalah akhir dari {i>data bin<i}. Jika end tidak diisi, maka bin tidak memiliki ujung dan valid dari awal hingga +inf.
densities	array[number] Deret waktu proporsi pengguna yang mengalami nilai bin ini untuk metrik yang ditentukan. Kepadatan dibulatkan menjadi 4 angka desimal.

Persentil

Percentiles berisi nilai sintetis sebuah metrik pada persentil statistik tertentu. Metrik ini digunakan untuk memperkirakan nilai metrik seperti yang dialami oleh persentase pengguna dari jumlah total pengguna.

{
  "P75": value
}

Kolom
p75s	array[(integer | string)] Deret waktu nilai saat 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 dengan cara tertentu, jadi metrik direpresentasikan dengan cara ini dapat dianggap sebagai menghasilkan nilai yang berbeda alih-alih nilai numerik, dan pecahan mengekspresikan seberapa sering nilai tertentu yang berbeda diukur.

{
  "label_1": { "fractions": array[fraction]},
  "label_1": { "fractions": array[fraction]},
  ...
  "label_n": { "fractions": array[fraction]}
}

Sama seperti nilai kepadatan dalam bin histogram, setiap fraction adalah angka 0.0 <= value <= 1.0, dan jumlah tersebut bertambah hingga ~1,0. Saat metrik tidak tersedia untuk periode pengumpulan tertentu, maka entri yang sesuai akan "NaN" dalam semua larik pecahan.

Kolom
p75s	array[(integer | string)] Deret waktu nilai saat 75% pemuatan halaman mengalami metrik yang ditentukan pada atau lebih rendah dari nilai ini.

UrlNormalization

Objek yang mewakili tindakan normalisasi yang dilakukan untuk menormalisasi URL agar mencapai peluang pencarian yang berhasil yang lebih tinggi. Ini adalah perubahan otomatis sederhana yang diambil saat mencari url_pattern yang disediakan akan diketahui gagal. Tindakan yang rumit seperti pengalihan berikut tidak akan ditangani.

{
  "originalUrl": string,
  "normalizedUrl": string
}

Kolom
originalUrl	string URL asli yang diminta sebelum tindakan normalisasi apa pun.
normalizedUrl	string URL setelah tindakan normalisasi. Ini adalah URL pengalaman pengguna yang valid dan 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, yang ditawarkan tanpa biaya. Batas ini, dan penggunaan Anda saat ini, dapat dilihat di Google Cloud Console. Kuota yang melimpah ini seharusnya memadai untuk sebagian besar kasus penggunaan dan peningkatan kuota tidak dapat dilakukan.