Cara menggunakan CrUX API

Pelajari cara menggunakan Chrome UX Report API untuk mendapatkan akses ke data pengalaman pengguna nyata di jutaan situs.

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

Set data Chrome UX Report (CrUX) menunjukkan cara pengguna Chrome di dunia nyata menjelajahi tujuan populer di web. Sejak tahun 2017, saat set data yang dapat dikueri pertama kali dirilis di BigQuery, data kolom dari CrUX telah diintegrasikan ke alat developer seperti PageSpeed Insights, Dasbor CrUX, dan laporan Core Web Vitals di Search Console, sehingga memungkinkan developer mengukur dan memantau pengalaman pengguna nyata. Bagian yang selama ini tidak ada selama ini adalah alat yang menyediakan akses gratis dan RESTful ke data CrUX secara terprogram. Untuk membantu menjembatani kesenjangan tersebut, dengan senang hati kami mengumumkan rilis Chrome UX Report API yang baru!

API ini dibuat dengan tujuan memberikan akses yang sederhana, cepat, dan komprehensif kepada developer ke data CrUX. CrUX API hanya melaporkan data pengalaman pengguna kolom, tidak seperti PageSpeed Insights API saat ini, yang juga melaporkan data lab dari audit performa Lighthouse. CrUX API disederhanakan dan dapat dengan cepat menyajikan data pengalaman pengguna, sehingga sangat cocok untuk aplikasi audit real-time.

Untuk memastikan developer memiliki akses ke semua metrik yang paling penting—Core Web Vitals—mengaudit dan memantau Largest Contentful Paint (LCP), Interaction to Next Paint (INP), dan Pergeseran Tata Letak Kumulatif (CLS) di tingkat asal dan URL.

Jadi, mari kita pelajari lebih lanjut dan lihat cara menggunakannya.

Membuat kueri data asal

Asal dalam set data CrUX mencakup semua pengalaman tingkat halaman yang mendasarinya. Contoh berikut menunjukkan cara mengkueri CrUX API untuk data pengalaman pengguna origin menggunakan cURL di command line.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"origin": "https://web.dev"}'

Perintah curl terdiri dari tiga bagian:

  1. Endpoint URL API, termasuk kunci API pribadi pemanggil.
  2. Header Content-Type: application/json, yang menunjukkan bahwa isi permintaan berisi JSON.
  3. Isi permintaan berenkode JSON, yang menentukan asal https://web.dev.

Untuk melakukan hal yang sama di JavaScript, gunakan utilitas CrUXApiUtil, yang melakukan panggilan API dan menampilkan respons yang didekode (lihat juga varian GitHub kami untuk fitur lainnya, termasuk histori dan dukungan batch).

const CrUXApiUtil = {};
// Get your CrUX API key at https://goo.gle/crux-api-key.
CrUXApiUtil.API_KEY = '[YOUR_API_KEY]';
CrUXApiUtil.API_ENDPOINT = `https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=${CrUXApiUtil.API_KEY}`;
CrUXApiUtil.query = function (requestBody) {
  if (CrUXApiUtil.API_KEY == '[YOUR_API_KEY]') {
    throw 'Replace "YOUR_API_KEY" with your private CrUX API key. Get a key at https://goo.gle/crux-api-key.';
  }
  return fetch(CrUXApiUtil.API_ENDPOINT, {
    method: 'POST',
    body: JSON.stringify(requestBody)
  }).then(response => response.json()).then(response => {
    if (response.error) {
      return Promise.reject(response);
    }
    return response;
  });
};

Ganti [YOUR_API_KEY] dengan kunci Anda. Selanjutnya, panggil fungsi CrUXApiUtil.query dan teruskan objek isi permintaan.

CrUXApiUtil.query({
  origin: 'https://web.dev'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

Jika data untuk asal ini ada, respons API adalah objek berenkode JSON yang berisi metrik yang mewakili distribusi pengalaman pengguna. Metrik distribusi adalah bin histogram dan persentil.

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.7925068547983514
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.1317422195536863
          },
          {
            "start": 4000,
            "density": 0.07575092564795324
          }
        ],
        "percentiles": {
          "p75": 2216
        }
      },
      // ...
    }
  }
}

Properti start dan end objek histogram mewakili rentang nilai yang dialami pengguna untuk metrik tertentu. Properti density merepresentasikan proporsi pengalaman pengguna dalam rentang tersebut. Dalam contoh ini, 79% pengalaman pengguna LCP di semua halaman web.dev berada di bawah 2.500 milidetik, yang merupakan status "baik" Nilai minimum LCP. Nilai percentiles.p75 berarti 75% pengalaman pengguna dalam distribusi ini kurang dari 2.216 milidetik. Pelajari struktur respons lebih lanjut dalam dokumentasi isi respons.

Error

Jika CrUX API tidak memiliki data untuk origin tertentu, CrUX API akan merespons dengan pesan error berenkode JSON:

{
  "error": {
    "code": 404,
    "message": "chrome ux report data not found",
    "status": "NOT_FOUND"
  }
}

Untuk men-debug error ini, periksa terlebih dahulu apakah asal yang diminta dapat dijelajahi secara publik. Anda dapat mengujinya dengan memasukkan origin ke kolom URL browser dan membandingkannya dengan URL final setelah pengalihan. Masalah umum mencakup penambahan atau penghapusan subdomain dan penggunaan protokol HTTP yang salah.

Error
{"origin": "http://www.web.dev"}

Origin ini salah menyertakan protokol http:// dan subdomain www..

Berhasil
{"origin": "https://web.dev"}

Origin ini dapat dijelajahi secara publik.

Jika origin yang diminta adalah versi yang dapat dinavigasi, error ini juga dapat terjadi jika origin tidak memiliki jumlah sampel yang cukup. Semua origin dan URL yang disertakan dalam set data harus memiliki jumlah sampel yang memadai untuk menganonimkan setiap pengguna. Selain itu, origin dan URL harus dapat diindeks secara publik. Lihat metodologi CrUX untuk mempelajari lebih lanjut bagaimana situs disertakan dalam set data.

Data URL kueri

Anda telah melihat cara membuat kueri CrUX API untuk keseluruhan pengalaman pengguna di origin. Untuk membatasi hasil ke halaman tertentu, gunakan parameter permintaan url.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://web.dev/fast/"}'

Perintah cURL ini mirip dengan contoh asal, kecuali bahwa isi permintaan menggunakan parameter url untuk menentukan halaman yang akan dicari.

Untuk membuat kueri data URL dari CrUX API di JavaScript, panggil fungsi CrUXApiUtil.query menggunakan parameter url dalam isi permintaan.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

Jika data untuk URL ini ada dalam set data CrUX, API akan menampilkan respons yang dienkode JSON. Contoh:

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.8477304539092148
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.08988202359528057
          },
          {
            "start": 4000,
            "density": 0.062387522495501155
          }
        ],
        "percentiles": {
          "p75": 1947
        }
      },
      // ...
    }
  }
}

Bentuk benar, hasil menunjukkan bahwa https://web.dev/fast/ memiliki 85% status "baik" Pengalaman LCP dan persentil ke-75 sebesar 1.947 milidetik, yang sedikit lebih baik daripada distribusi seluruh origin.

Normalisasi URL

CrUX API dapat menormalisasi URL yang diminta agar lebih cocok dengan daftar URL yang dikenal. Misalnya, kueri untuk URL https://web.dev/fast/#measure-performance-in-the-field akan menghasilkan data untuk https://web.dev/fast/ karena normalisasi. Jika hal ini terjadi, objek urlNormalizationDetails akan disertakan dalam respons.

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/"
    },
    "metrics": { ... }
  },
  "urlNormalizationDetails": {
    "normalizedUrl": "https://web.dev/fast/",
    "originalUrl": "https://web.dev/fast/#measure-performance-in-the-field"
  }
}

Pelajari normalisasi URL lebih lanjut di dokumentasi CrUX.

Kueri menurut faktor bentuk

Pengalaman pengguna dapat sangat bervariasi, bergantung pada pengoptimalan situs, kondisi jaringan, dan perangkat. Untuk lebih memahami perbedaan ini, lihat perincian performa URL dan origin menggunakan dimensi formFactor dari CrUX API.

API ini mendukung tiga nilai faktor bentuk eksplisit: DESKTOP, PHONE, dan TABLET. Selain origin atau URL, tentukan salah satu nilai ini di isi permintaan untuk membatasi hasil hanya untuk pengalaman pengguna tersebut. Contoh ini menunjukkan cara membuat kueri API berdasarkan faktor bentuk menggunakan cURL.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://web.dev/fast/", "formFactor": "PHONE"}'

Untuk membuat kueri data khusus faktor bentuk ke CrUX API menggunakan JavaScript, panggil fungsi CrUXApiUtil.query menggunakan parameter url dan formFactor dalam isi permintaan.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/',
  formFactor: 'PHONE'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

Menghapus parameter formFactor sama dengan meminta data untuk semua faktor bentuk yang digabungkan.

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/",
      "formFactor": "PHONE"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.778631284916204
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.13943202979515887
          },
          {
            "start": 4000,
            "density": 0.08193668528864119
          }
        ],
        "percentiles": {
          "p75": 2366
        }
      },
    // ...
    }
  }
}

Kolom key pada respons akan melakukan echo kembali ke konfigurasi permintaan formFactor untuk mengonfirmasi bahwa hanya pengalaman ponsel yang disertakan.

Ingat kembali dari bagian sebelumnya bahwa 85% pengalaman pengguna di halaman ini memiliki "baik" LCP. Bandingkan dengan pengalaman khusus ponsel, dan hanya 78% yang dianggap "baik". Persentil ke-75 juga lebih lambat di antara pengalaman ponsel, naik dari 1.947 milidetik menjadi 2.366 milidetik. Segmentasi menurut faktor bentuk berpotensi menyoroti perbedaan yang lebih ekstrem dalam pengalaman pengguna.

Menilai performa Core Web Vitals

Program Data Web Inti menentukan target yang membantu menentukan apakah pengalaman pengguna atau distribusi pengalaman dapat dianggap "baik". Pada contoh berikut, kami menggunakan CrUX API dan fungsi CrUXApiUtil.query untuk menilai apakah distribusi metrik Core Web Vitals (LCP, INP, CLS) halaman web "baik".

CrUXApiUtil.query({
  url: 'https://web.dev/fast/'
}).then(response => {
  assessCoreWebVitals(response);
}).catch(response => {
  console.error(response);
});

function assessCoreWebVitals(response) {
  // See https://web.dev/vitals/#core-web-vitals.
  const CORE_WEB_VITALS = [
    'largest_contentful_paint',
    'interaction_to_next_paint',
    'cumulative_layout_shift'
  ];
  CORE_WEB_VITALS.forEach(metric => {
    const data = response.record.metrics[metric];
    if (!data) {
      console.log('No data for', metric);
      return;
    }
    const p75 = data.percentiles.p75;
    const threshold = data.histogram[0].end;
    // A Core Web Vitals metric passes the assessment if
    // its 75th percentile is under the "good" threshold.
    const passes = p75 < threshold;
    console.log(`The 75th percentile (${p75}) of ${metric} ` +
        `${passes ? 'passes' : 'does not pass'} ` +
        `the Core Web Vitals "good" threshold (${threshold}).`)
  });
}

Hasilnya menunjukkan bahwa halaman ini lulus penilaian Core Web Vitals untuk ketiga metrik.

The 75th percentile (1973) of largest_contentful_paint passes the Core Web Vitals "good" threshold (2500).
The 75th percentile (20) of interaction_to_next_paint passes the Core Web Vitals "good" threshold (200).
The 75th percentile (0.05) of cumulative_layout_shift passes the Core Web Vitals "good" threshold (0.10).

Dikombinasikan dengan cara otomatis untuk memantau hasil API, data dari CrUX dapat digunakan untuk memastikan pengalaman pengguna nyata menjadi cepat dan tetap cepat. Untuk informasi selengkapnya tentang Core Web Vitals dan cara mengukurnya, lihat Data Web dan Alat untuk mengukur Core Web Vitals.

Apa langkah selanjutnya?

Fitur yang disertakan dalam versi awal CrUX API hanya sebagian kecil dari jenis insight yang dimungkinkan dengan CrUX. Pengguna set data CrUX di BigQuery mungkin sudah mengenal beberapa fitur lanjutan lainnya, termasuk:

  • Metrik tambahan
    • first_paint
    • dom_content_loaded
    • onload
    • time_to_first_byte
    • notification_permissions
  • Dimensi tambahan
    • month
    • country
    • effective connection type (ECT)
  • Perincian tambahan
    • histogram yang mendetail
    • persentil lebih banyak

Baca dokumen CrUX API resmi untuk mendapatkan kunci API dan mempelajari berbagai contoh aplikasi lainnya. Kami harap Anda mencobanya dan kami ingin mendengar pertanyaan atau masukan apa pun yang mungkin Anda miliki, jadi hubungi kami di forum diskusi CrUX. Untuk terus mendapatkan info terbaru tentang segala hal yang telah kami rencanakan untuk CrUX API, berlanggananlah ke forum pengumuman CrUX atau ikuti kami di Twitter di @ChromeUXReport.