API CrUX

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

Cobalah!

Kasus penggunaan umum

CrUX API memungkinkan pembuatan kueri metrik pengalaman pengguna untuk URI tertentu seperti "Dapatkan metrik untuk asal https://example.com".

Kunci API CrUX

Penggunaan CrUX API memerlukan kunci API Google Cloud yang disediakan untuk penggunaan Chrome UX Report API.

Mendapatkan dan menggunakan kunci API

Dapatkan Kunci

Atau buat satu di halaman Credentials.

Setelah 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, ID ini adalah halaman web dan situs.

Asal

Jika ID adalah origin, semua data yang ada untuk semua halaman di 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 tempat kumpulan data dikumpulkan, 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, jika dimensi tersebut tidak ditentukan, dimensi akan digabungkan ke semua nilai. Misalnya, menentukan tidak adanya faktor bentuk menunjukkan bahwa kumpulan 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 perangkat umum yang dibagi menjadi PHONE, TABLET, dan DESKTOP.

Jenis Koneksi Efektif

Effective Connection Type adalah perkiraan 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 ke 4 tempat desimal (perhatikan bahwa metrik cumulative_layout_shift dienkode ulang sebagai string, sehingga tidak dianggap sebagai float dan dilaporkan ke 2 tempat desimal dalam string).

Histogram

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

Histogram tiga bin 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, contoh metrik diukur antara 0 md dan 1.000 md. Satuan metrik tidak terdapat dalam histogram ini, dalam hal ini kita akan mengasumsikannya dalam milidetik.

Selain itu, 49,91% pemuatan halaman menampilkan nilai metrik antara 1.000 md dan 3.000 md,dan 11, 92% melihat 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 diberikan untuk metrik tersebut. Mereka didasarkan pada set lengkap data yang tersedia dan bukan data yang dikelompokkan akhir, jadi mereka belum tentu cocok dengan persentil terinterpolasi yang didasarkan pada histogram binned akhir.

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

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

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 pengelompokan faktor bentuk (atau perangkat) yang dicakup oleh kueri tertentu:

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

Dalam hal ini, 3,77% pemuatan halaman diukur pada desktop, 2,88% pada tablet, dan 93,35% pada ponsel, memberikan 100% secara total.

Jenis nilai metrik

Nama Metrik CrUX API Jenis Data Unit Metrik Agregasi Statistik Dokumentasi
cumulative_layout_shift 2 tempat desimal yang dienkode ganda 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
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 lcp
experimental_time_to_first_byte int milidetik histogram dengan tiga bin, persentil dengan p75 ttfb
form_factors 4 angka desimal ganda persen pemetaan dari faktor bentuk ke pecahan faktor bentuk
navigation_types 4 angka desimal ganda persen pemetaan dari jenis navigasi ke pecahan jenis navigasi
round_trip_time int milidetik persentil dengan p75 rtt

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
round_trip_time t/a

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 yang lebih baik tentang data dan apakah data tersebut telah diperbarui untuk hari itu atau menampilkan data yang sama seperti kemarin.

Perlu diketahui bahwa CrUX API kira-kira dua hari lebih lambat dari tanggal hari ini karena menunggu data yang diselesaikan pada hari itu, dan ada 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, 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: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"]}'

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 nilai formFactor tidak 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 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.

Hal ini mirip 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 pembaruan; dan kami berupaya sebaik mungkin setiap hari.

Skema

Ada endpoint tunggal 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 harus mencakup data record.

Kolom ini menggunakan nilai ["offline", "slow-2G", "2G", "3G", "4G"] seperti yang ditentukan dalam spesifikasi Network Information API

Catatan: Jika jenis koneksi efektif tidak ditentukan, kumpulan data khusus dengan data gabungan pada semua jenis koneksi efektif akan ditampilkan.
formFactor

enum (FormFactor)

Faktor bentuk adalah dimensi kueri yang menentukan class perangkat yang harus mencakup data record.

Kolom ini menggunakan nilai DESKTOP, PHONE, atau TABLET.

Catatan: Jika faktor bentuk tidak ditentukan, data khusus dengan data gabungan pada semua faktor bentuk akan ditampilkan.
metrics[]

string

Metrik yang harus disertakan dalam respons. Jika tidak ada yang ditentukan, 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. Kolom tersebut hanya dapat berupa salah satu dari hal berikut:
origin

string

"Asal" url_pattern mengacu pada pola URL yang merupakan asal dari sebuah situs web.

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 largest contentful paint desktop untuk 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 di 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 dari semua faktor bentuk akan ditampilkan.
effectiveConnectionType

string

Jenis koneksi efektif adalah kelas koneksi umum yang dialami semua pengguna untuk rekaman ini. Kolom ini menggunakan nilai ["offline", "slow-2G", "2G", "3G", "4G"] seperti yang ditentukan di: https://wicg.github.io/netinfo/#effective-connection-types

Jika jenis koneksi efektif tidak ditentukan, data gabungan di semua jenis koneksi efektif 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 data ini.

Catatan: Saat menentukan origin, data untuk pemuatan berdasarkan 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 gabungan untuk satu metrik performa web, seperti first contentful paint. Grafik ini dapat berisi histogram ringkasan penggunaan Chrome di dunia nyata sebagai serangkaian data persentil tertentu bins (misalnya p75), atau mungkin mengandung 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 bin dan kepadatan semua bin akan bertambah hingga ~1.
percentiles

object (Percentiles)

Persentil umum berguna dari Metrik. Jenis nilai untuk persentil akan sama dengan jenis nilai yang diberikan untuk bin Histogram.
fractions

object (Fractions)

Objek ini berisi pecahan berlabel, yang berjumlah ~1.

Fraksi dibulatkan ke 4 tempat desimal.

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, oleh karena itu 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,
  "density": number
}
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 akhir dan valid dari awal hingga +inf.
density

number

Proporsi pengguna yang mengalami nilai bin ini untuk metrik tertentu.

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
p75

(integer | string)

75% pemuatan halaman mengalami metrik yang diberikan pada atau kurang dari nilai ini.

Pecahan

Fractions berisi pecahan berlabel yang jika dijumlahkan mencapai ~1. Setiap label mendeskripsikan pemuatan halaman, jadi metrik yang direpresentasikan dengan cara ini dapat dianggap sebagai menghasilkan nilai yang berbeda dan bukan nilai numerik, dan pecahan mengekspresikan frekuensi nilai yang berbeda diukur.

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

Sama seperti nilai kepadatan dalam bin histogram, setiap fraction adalah angka 0.0 <= value <= 1.0, dan jumlah tersebut bertambah hingga ~1,0.

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 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 melimpah ini seharusnya memadai untuk sebagian besar kasus penggunaan dan peningkatan kuota tidak dapat dilakukan.