API CrUX

CrUX API memberikan akses latensi rendah ke data gabungan pengalaman pengguna nyata di tingkat perincian halaman dan origin.

Kasus penggunaan umum

CrUX API memungkinkan kueri metrik pengalaman pengguna untuk URI tertentu seperti "Get metrics for the https://example.com origin".

Kunci API CrUX

Penggunaan CrUX API memerlukan kunci Google Cloud API. 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 kumpulan data tersebut berisi informasi tentang pemuatan yang terjadi di perangkat seluler. Setiap dimensi akan memiliki sejumlah nilai tertentu, dan secara implisit, ketidakmampuan untuk menetapkan dimensi tersebut berarti bahwa dimensi digabungkan pada semua nilai. Misalnya, menentukan tidak ada faktor bentuk menunjukkan bahwa data berisi informasi tentang pemuatan yang terjadi pada faktor bentuk apa pun.

Faktor Bentuk

Class perangkat yang digunakan pengguna akhir untuk membuka halaman. Ini adalah class umum perangkat yang dibagi menjadi PHONE, TABLET, dan DESKTOP.

Jenis Koneksi Efektif

Effective Connection Type adalah estimasi kualitas koneksi perangkat saat membuka halaman. Ini adalah class umum yang dibagi menjadi offline, slow-2G, 2G, 3G, dan 4G.

Metrik

Kami melaporkan metrik sebagai agregasi statistik, dalam histogram, persentil, dan fraksi.

Nilai floating point dibulatkan menjadi 4 tempat desimal (perhatikan bahwa metrik cumulative_layout_shift dienkode ganda sebagai string, sehingga tidak dianggap sebagai float dan dilaporkan ke 2 angka desimal dalam string).

Histogram

Saat metrik ditampilkan dalam histogram, kami menampilkan persentase pemuatan halaman yang termasuk dalam rentang tertentu untuk metrik tersebut.

Histogram tiga bin sederhana untuk contoh metrik terlihat seperti ini:

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

Data ini menunjukkan bahwa untuk 38, 18% pemuatan halaman,metrik contoh diukur antara 0 md dan 1.000 md. Satuan metrik tidak dimuat dalam histogram ini, dalam hal ini kita akan mengasumsikan milidetik.

Selain itu, 49,91% pemuatan halaman memperoleh nilai metrik antara 1.000 md hingga 3.000 md, dan 11,92% memperoleh nilai yang lebih besar dari 3.000 md.

Persentil

Metrik juga dapat berisi persentil yang dapat berguna untuk analisis tambahan. Kami melaporkan nilai metrik tertentu pada persentil yang ditentukan untuk metrik tersebut. Tabel sementara didasarkan pada set lengkap data yang tersedia, bukan data yang digabungkan akhir, sehingga tidak selalu cocok dengan persentil terinterpolasi yang didasarkan pada histogram kelompok akhir.

{
  "percentiles": {
    "p75": 2063
  }
}

Dalam contoh ini, setidaknya 75% pemuatan halaman diukur dengan nilai metrik <= 2063.

Catatan: Nilai untuk setiap persentil diperoleh secara sintetis, hal ini tidak berarti bahwa setiap pengguna benar-benar mengalami nilai yang ditunjukkan, hanya beberapa persentase pemuatan halaman yang mengalami nilai metrik yang lebih kecil dari nilai yang diberikan.

Pecahan

Pecahan menunjukkan persentase pemuatan halaman yang dapat diberi label dengan cara tertentu. Dalam hal ini, nilai metrik adalah label tersebut.

Misalnya, metrik form_factors terdiri dari objek fractions yang mencantumkan perincian faktor bentuk (atau perangkat) yang dicakup oleh kueri tertentu:

"form_factors": {
  "fractions": {
    "desktop": 0.0377,
    "tablet": 0.0288,
    "phone": 0.9335
  }
}

Dalam kasus ini, 3,77% pemuatan halaman diukur di desktop, 2,88% di tablet, dan 93,35% di ponsel, sehingga totalnya 100%.

Jenis nilai metrik

Nama Metrik CrUX API	Jenis Data	Unit Metrik	Agregasi Statistik	Dokumentasi
cumulative_layout_shift	2 angka desimal ganda dienkode sebagai string	tanpa unit	histogram dengan tiga bin, persentil dengan p75	cls
first_contentful_paint	int	milidetik	histogram dengan tiga bin, persentil dengan p75	fcp
first_input_delay (tidak digunakan lagi)	int	milidetik	histogram dengan tiga bin, persentil dengan p75	fid
interaction_to_next_paint	int	milidetik	histogram dengan tiga bin, persentil dengan p75	inp
largest_contentful_paint	int	milidetik	histogram dengan tiga bin, persentil dengan p75	LPC
experimental_time_to_first_byte	int	milidetik	histogram dengan tiga bin, persentil dengan p75	ttfb
form_factors	angka 4 desimal ganda	persen	pemetaan dari faktor bentuk ke fraksi	faktor bentuk
navigation_types	angka 4 desimal ganda	persen	pemetaan dari jenis navigasi ke fraksi	jenis navigasi

Pemetaan nama metrik BigQuery

Nama Metrik CrUX API	Nama Metrik BigQuery
cumulative_layout_shift	layout_instability.cumulative_layout_shift
first_contentful_paint	first_contentful_paint
first_input_delay	first_input.delay
interaction_to_next_paint	interaction_to_next_paint
largest_contentful_paint	largest_contentful_paint
experimental_time_to_first_byte	experimental.time_to_first_byte
navigation_types	navigation_types
form_factors	t/a

Catatan: Di CrUX BigQuery, kepadatan histogram hingga 100% per origin di seluruh faktor bentuk, sehingga metrik form_factors yang kami dukung di API dinyatakan sebagai kepadatan histogram untuk first_contentful_paint.

Periode pengumpulan

Mulai Oktober 2022, CrUX API berisi objek collectionPeriod dengan kolom firstDate dan endDate yang mewakili tanggal mulai dan akhir periode agregasi. Contoh:

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }

Hal ini memungkinkan pemahaman data yang lebih baik dan apakah data telah diperbarui untuk hari itu atau mengembalikan data yang sama seperti kemarin.

Perhatikan bahwa CrUX API kira-kira dua hari lebih lambat dari tanggal hari ini karena menunggu data yang telah selesai untuk hari tersebut, dan ada beberapa waktu pemrosesan yang diperlukan sebelum tersedia di API. Zona waktu yang digunakan adalah Waktu Standar Pasifik (PST) tanpa perubahan untuk waktu musim panas.

Contoh kueri

Kueri dikirim sebagai objek JSON menggunakan permintaan POST ke https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" dengan data kueri sebagai objek JSON dalam isi POST:

{
  "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:queryRecord?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 modifikasi. Misalnya, command line cmd.exe tidak mengizinkan tanda kutip tunggal untuk parameter, atau lanjutan baris (\), sehingga memerlukan penggunaan tanda kutip ganda (mengabaikan 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 (tidak digunakan lagi)
• interaction_to_next_paint
• largest_contentful_paint
• experimental_time_to_first_byte
• navigation_types
• form_factors (hanya dilaporkan jika tidak ada formFactor yang ditentukan dalam permintaan)

Jika tidak ada nilai formFactor yang diberikan, nilai akan digabungkan di semua faktor bentuk.

Lihat Menggunakan Chrome UX Report API untuk contoh kueri lainnya.

Pipeline data

Set data CrUX diproses melalui pipeline untuk menggabungkan, menggabungkan, dan memfilter data sebelum tersedia menggunakan 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.

Ini serupa dengan cara set data CrUX di BigQuery menggabungkan laporan bulanan.

Info terbaru harian

Data diperbarui setiap hari sekitar pukul 04.00 UTC. Tidak ada perjanjian tingkat layanan untuk waktu update. Proses ini dijalankan dengan upaya terbaik setiap hari.

Perhatian: Data tidak akan berbeda pada hari yang sama setelah diperbarui sekitar pukul 04.00 UTC, panggilan berulang akan memberikan hasil yang sama.

Skema

Ada satu endpoint untuk CrUX 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:queryRecord

URL menggunakan sintaksis gRPC Transcoding.

Isi permintaan

Isi permintaan harus berisi data dengan struktur berikut:

{
  "effectiveConnectionType": string,
  "formFactor": enum (FormFactor),
  "metrics": [
    string
  ],

  // 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
effectiveConnectionType	string Jenis koneksi efektif adalah dimensi kueri yang menentukan class jaringan efektif yang seharusnya memiliki data kumpulan data. Kolom ini menggunakan nilai ["offline", "slow-2G", "2G", "3G", "4G"] seperti yang ditentukan dalam spesifikasi Network Information API Catatan: Jika tidak ada jenis koneksi efektif yang ditentukan, maka kumpulan data khusus dengan data gabungan atas semua jenis koneksi efektif akan ditampilkan.
formFactor	enum (FormFactor) Faktor bentuk adalah dimensi kueri yang menentukan class perangkat tempat data kumpulan akan berada. Kolom ini menggunakan nilai DESKTOP, PHONE, atau TABLET. Catatan: Jika tidak ada faktor bentuk yang ditentukan, data khusus dengan data gabungan atas semua faktor bentuk akan ditampilkan.
metrics[]	string Metrik yang harus disertakan dalam respons. Jika tidak ada yang ditentukan, maka metrik apa pun yang ditemukan akan ditampilkan. Nilai yang diizinkan: ["cumulative_layout_shift", "first_contentful_paint", "first_input_delay", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]
Kolom union url_pattern. url_pattern adalah ID utama untuk pencarian data. Data tersebut hanya dapat berupa salah satu dari hal berikut:
origin	string "Origin" url_pattern mengacu pada pola URL yang merupakan origin situs. Contoh: "https://example.com", "https://cloud.google.com"
url	string url_pattern url mengacu pada pola URL yang merupakan URL arbitrer. Contoh: "https://example.com/, https://cloud.google.com/why-google-cloud/"

Misalnya, untuk meminta nilai Large Contentful Paint untuk desktop di halaman beranda dokumentasi developer Chrome:

{
  "url": "https://developer.chrome.com/docs/",
  "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": {
      "formFactor": "DESKTOP",
      "url": "https://developer.chrome.com/docs/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.9815
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.0108
          },
          {
            "start": 4000,
            "density": 0.0077
          }
        ],
        "percentiles": {
          "p75": 651
        }
      }
    },
    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }
  }
}

Kunci

Key menentukan semua dimensi yang mengidentifikasi data ini sebagai unik.

{
  "effectiveConnectionType": string,
  "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 atas semua faktor bentuk akan ditampilkan.
effectiveConnectionType	string Jenis koneksi efektif adalah class koneksi umum yang dialami semua pengguna untuk kumpulan data ini. Kolom ini menggunakan nilai ["offline", "slow-2G", "2G", "3G", "4G"] seperti yang ditentukan dalam: https://wicg.github.io/netinfo/#effective-connection-types Jika jenis koneksi efektif tidak ditentukan, data gabungan atas semua jenis koneksi efektif akan ditampilkan.
Kolom union url_pattern. Pola URL adalah URL tempat data akan diterapkan. url_pattern hanya ada berupa salah satu diantara berikut:
origin	string origin menentukan tempat asal 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	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 gabungan untuk satu metrik performa web, seperti first contentful paint. Data ini dapat berisi histogram ringkasan penggunaan Chrome di dunia nyata sebagai serangkaian bins, data persentil tertentu (seperti p75), atau mungkin berisi pecahan berlabel.

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

atau

{
  "fractions": {
    object (Fractions)
  }
}

Kolom
histogram[]	object (Bin) Histogram pengalaman pengguna untuk metrik. Histogram akan memiliki setidaknya satu {i>bin<i} dan kepadatan semua {i>bin<i} akan berjumlah ~1.
percentiles	object (Percentiles) Persentil umum yang berguna dari Metrik. Jenis nilai untuk persentil akan sama dengan jenis nilai yang diberikan untuk kelompok Histogram.
fractions	object (Fractions) Objek ini berisi pecahan berlabel, yang berjumlah ~1. Pecahan dibulatkan menjadi 4 angka di belakang koma.

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,
  "density": number
}

Kolom
start	(integer | string) {i>Start<i} adalah awal dari {i>data bin<i}.
end	(integer | string) {i>End<i} adalah akhir dari {i>data bin<i}. Jika end tidak terisi, tempat tidak memiliki akhir dan valid dari awal hingga +inf.
density	number 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
p75	(integer | string) 75% pemuatan halaman mengalami metrik yang ditentukan pada atau kurang dari nilai ini.

Pecahan

Fractions berisi pecahan berlabel yang berjumlah ~1. Setiap label menjelaskan pemuatan halaman dengan cara tertentu, sehingga metrik yang ditampilkan dengan cara ini dapat dianggap sebagai produksi nilai yang berbeda, bukan nilai numerik, dan pecahan tersebut mengungkapkan seberapa sering nilai yang berbeda diukur.

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

Mirip dengan nilai kepadatan dalam kumpulan histogram, setiap fraction adalah angka 0.0 <= value <= 1.0, dan jumlahnya mencapai ~1,0.

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	string URL asli yang diminta sebelum tindakan normalisasi.
normalizedUrl	string URL setelah tindakan normalisasi. Ini adalah URL pengalaman pengguna yang valid yang dapat dicari secara wajar.

Batas kapasitas

CrUX API dibatasi hingga 150 kueri per menit per project Google Cloud, 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.