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 kueri metrik pengalaman pengguna untuk URI tertentu seperti "Dapatkan metrik untuk origin 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

Atau, buat di halaman Credentials.

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

Kunci API aman untuk disematkan di URL; kunci API tidak memerlukan encoding apa pun.

Lihat Contoh kueri.

Model data

Bagian ini menjelaskan struktur data dalam permintaan dan respons.

Rekam

Bagian informasi terpisah tentang halaman atau situs. 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 data 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 seperti yang ditetapkan oleh peta situs ini:

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

Artinya, saat membuat kueri Chrome UX Report 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, karena semuanya adalah halaman di origin tersebut.

URL

Jika ID-nya adalah URL, hanya data untuk URL tertentu tersebut yang akan ditampilkan. Melihat kembali peta situs origin 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 digunakan untuk menggabungkan data, misalnya faktor bentuk PHONE menunjukkan bahwa data 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 tersebut akan digabungkan ke semua nilai. Misalnya, tidak menentukan faktor bentuk menunjukkan bahwa data tersebut berisi informasi tentang beban 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.

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 adalah bilangan ganda yang dienkode 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,metrik contoh diukur antara 0 md dan 1.000 md. Satuan metrik tidak terdapat dalam histogram ini, dalam hal ini kita akan mengasumsikan milidetik.

Selain itu, 49,91% pemuatan halaman melihat nilai metrik antara 1.000 md dan 3.000 md, dan 11,92% melihat nilai 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 tertentu untuk metrik tersebut. Data ini didasarkan pada kumpulan lengkap data yang tersedia, bukan data bin akhir, sehingga tidak selalu cocok dengan persentil yang diinterpolasi yang didasarkan pada histogram bin akhir.

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

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

Pecahan

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

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 di desktop, 2,88% di tablet, dan 93,35% di ponsel, sehingga totalnya 100%.

Jenis nilai metrik

Pemetaan nama metrik BigQuery

Periode pengumpulan

Mulai Oktober 2022, CrUX API berisi objek collectionPeriod dengan kolom firstDate dan endDate yang mewakili tanggal awal 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 sudah diperbarui untuk hari itu atau menampilkan data yang sama seperti kemarin.

Periode pengumpulan juga tersedia di PageSpeed Insights:

Selain itu, collectionPeriod akan selalu menampilkan 28 hari, meskipun datanya tidak untuk 28 hari penuh (misalnya, jika halaman diluncurkan kurang dari 28 hari yang lalu). collectionPeriod adalah jangka waktu penggabungan data CrUX, tidak harus jangka waktu yang diwakili data.

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
• 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 mengetahui 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 dalam Laporan UX Chrome pada waktu tertentu sebenarnya adalah 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 update; update dijalankan berdasarkan upaya terbaik setiap hari.

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 halaman atau origin 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:

{
  "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.
}

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

{
  "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.
}

Metrik

metric adalah kumpulan data pengalaman pengguna gabungan untuk satu metrik performa web, seperti first contentful paint. File ini mungkin berisi histogram ringkasan penggunaan Chrome di dunia nyata sebagai serangkaian bins, data persentil tertentu (seperti p75), atau mungkin berisi fraksi berlabel.

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

atau

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

Kotak

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 bin diberikan dalam jenis nilai metrik yang diwakilinya. Misalnya, first contentful paint diukur dalam milidetik dan ditampilkan sebagai int, sehingga bucket metriknya akan menggunakan int32 untuk jenis awal dan akhirnya. Namun, pergeseran tata letak kumulatif diukur dalam desimal tanpa satuan dan ditampilkan sebagai desimal yang dienkode sebagai string, sehingga bucket metriknya akan menggunakan string untuk jenis nilainya.

{
  "start": value,
  "end": value,
  "density": number
}

Persentil

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

{
  "P75": value
}

Pecahan

Fractions berisi pecahan berlabel yang jumlahnya hingga ~1. Setiap label menjelaskan muat halaman dengan cara tertentu, sehingga metrik yang direpresentasikan dengan cara ini dapat dianggap sebagai menghasilkan nilai yang berbeda, bukan nilai numerik, dan fraksi menunjukkan frekuensi pengukuran nilai tertentu yang berbeda.

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

Sama seperti nilai kepadatan dalam bucket histogram, setiap fraction adalah angka 0.0 <= value <= 1.0, dan jumlahnya mencapai ~1,0.

UrlNormalization

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

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

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 Konsol Google Cloud. Kuota yang besar ini seharusnya sudah cukup untuk sebagian besar kasus penggunaan dan Anda tidak dapat membayar untuk meningkatkan kuota.