API CrUX

CrUX API memberikan akses latensi rendah ke data pengalaman pengguna nyata 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 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 Anda memiliki kunci API, aplikasi Anda dapat menambahkan parameter kueri key=yourAPIKey ke semua URL permintaan.

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

Lihat Contoh kueri.

Model data

Bagian ini menjelaskan struktur data dalam permintaan dan respons.

Rekam

Informasi terpisah tentang halaman atau situs. Data dapat memiliki data yang spesifik untuk ID dan untuk kombinasi dimensi tertentu. Data dapat berisi data untuk satu atau beberapa metrik.

ID

ID menentukan 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, origin http://www.example.com 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 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 bersama, karena semuanya adalah halaman di bawah origin tersebut.

URL

Jika ID-nya adalah URL, hanya data untuk URL spesifik tersebut yang akan ditampilkan. Melihat 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 menjadi dasar agregasi 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, tidak adanya penentuan dimensi tersebut akan berarti bahwa dimensi tersebut digabungkan di semua nilai. Misalnya, tidak menentukan 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.

Metrik

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

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

Histogram

Jika metrik dinyatakan dalam histogram, kami akan menampilkan persentase pemuatan halaman yang termasuk 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 mengasumsikan milidetik.

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

{
  "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 metriknya adalah label ini.

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 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 mulai dan akhir periode penggabungan. 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.

Periode pengumpulan juga tersedia di PageSpeed Insights:

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

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_cumulative_layout_shift_with_softnavs
• experimental_first_contentful_paint_with_softnavs
• experimental_interaction_to_next_paint_with_softnavs
• experimental_largest_contentful_paint_with_softnavs
• experimental_navigation_types_with_softnavs
• experimental_time_to_first_byte
• largest_contentful_paint_resource_type
• largest_contentful_paint_image_time_to_first_byte
• largest_contentful_paint_image_resource_load_delay
• largest_contentful_paint_image_resource_load_duration
• largest_contentful_paint_image_element_render_delay
• navigation_types
• round_trip_time
• form_factors (hanya dilaporkan jika tidak ada formFactor yang ditentukan dalam permintaan)
• experimental_ad_count (hanya dilaporkan untuk halaman yang disertakan dalam metrik iklan)
• experimental_ad_density (hanya dilaporkan untuk halaman yang disertakan dalam metrik iklan)
• experimental_ad_cpu (hanya dilaporkan untuk halaman yang disertakan dalam metrik iklan)
• experimental_ad_kilobytes (hanya dilaporkan untuk halaman yang disertakan dalam metrik iklan)

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, mengagregasi, dan memfilter data sebelum tersedia menggunakan API.

Rata-rata penggiliran

Data dalam Chrome UX Report adalah rata-rata penggiliran 28 hari dari metrik gabungan. Artinya, data yang ditampilkan di Chrome UX Report 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 akan menampilkan record yang berisi satu atau beberapa metrics yang sesuai dengan data performa tentang origin atau halaman yang diminta.

Permintaan HTTP

POST https://chromeuxreport.googleapis.com/v1/records:queryRecord

URL ini 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. Laporan ini dapat berisi histogram ringkasan penggunaan Chrome di dunia nyata sebagai rangkaian bins, data persentil tertentu (seperti p75), atau dapat berisi pecahan berlabel.

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

atau

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

Kotak

bin adalah bagian data diskret 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 bin 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 bin metriknya akan menggunakan string untuk jenis nilainya.

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

Persentil

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

{
  "P75": value
}

Pecahan

Fractions berisi pecahan berlabel yang berjumlah ~1. Setiap label mendeskripsikan pemuatan halaman dengan cara tertentu, sehingga metrik yang direpresentasikan dengan cara ini dapat dianggap menghasilkan nilai yang berbeda, bukan nilai numerik, dan pecahan menyatakan seberapa sering nilai tertentu 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 jumlahnya mencapai ~1,0.

UrlNormalization

Objek yang mewakili tindakan normalisasi yang dilakukan untuk menormalisasi URL agar memiliki peluang pencarian yang lebih tinggi. Ini adalah perubahan dasar dan otomatis yang dilakukan saat pencarian url_pattern yang diberikan diketahui akan 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 cukup untuk sebagian besar kasus penggunaan dan Anda tidak dapat membayar untuk meningkatkan kuota.