Cara menggunakan CrUX API

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

Rick Viscomi

Shane Exterkamp

Set data Laporan UX Chrome (CrUX) menunjukkan pengalaman pengguna Chrome yang sebenarnya saat membuka tujuan populer di web. Sejak 2017, saat set data yang dapat dikueri pertama kali dirilis di BigQuery, data kolom dari CrUX telah diintegrasikan ke dalam alat developer seperti PageSpeed Insights, Dasbor CrUX, dan laporan Core Web Vitals Search Console, sehingga developer dapat mengukur dan memantau pengalaman pengguna sebenarnya. Bagian yang belum 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 telah dibuat dengan tujuan memberikan akses yang sederhana, cepat, dan komprehensif ke data CrUX bagi developer. CrUX API hanya melaporkan data pengalaman pengguna lapangan, tidak seperti PageSpeed Insights API yang ada, yang juga melaporkan data lab dari audit performa Lighthouse. CrUX API disederhanakan dan dapat menayangkan data pengalaman pengguna dengan cepat, sehingga sangat cocok untuk aplikasi audit real-time.

Untuk memastikan developer memiliki akses ke semua metrik yang paling penting—Core Web Vitals—CrUX API mengaudit dan memantau Largest Contentful Paint (LCP), Interaction to Next Paint (INP), dan Cumulative Layout Shift (CLS) di tingkat origin dan URL.

Jadi, mari kita pelajari dan lihat cara menggunakannya.

Coba API di halaman ini

Cobalah!

Membuat kueri data asal

Origin dalam set data CrUX mencakup semua pengalaman tingkat halaman yang mendasarinya. Contoh berikut menunjukkan cara membuat kueri 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"}'

Catatan: Semua permintaan API harus memberikan nilai untuk parameter key—[YOUR_API_KEY] dalam contoh sebelumnya dibiarkan sebagai placeholder. Dapatkan kunci CrUX API pribadi Anda seperti yang dijelaskan dalam dokumentasi CrUX API.

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 yang dienkode 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 dukungan batch dan histori).

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 ada untuk origin ini, respons API adalah objek berenkode JSON yang berisi metrik yang mewakili distribusi pengalaman pengguna. Metrik distribusi adalah histogram bin 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 dari objek histogram mewakili rentang nilai yang dialami pengguna untuk metrik tertentu. Properti density mewakili proporsi pengalaman pengguna dalam rentang tersebut. Dalam contoh ini, 79% pengalaman pengguna LCP di semua halaman web.dev kurang dari 2.500 milidetik, yang merupakan nilai minimum LCP "baik". Nilai percentiles.p75 berarti 75% pengalaman pengguna dalam distribusi ini kurang dari 2.216 milidetik. Pelajari lebih lanjut struktur respons dalam dokumentasi isi respons.

Error

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

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

Untuk men-debug error ini, periksa terlebih dahulu apakah origin yang diminta dapat dinavigasi secara publik. Anda dapat mengujinya dengan memasukkan origin ke kolom URL browser dan membandingkannya dengan URL final setelah pengalihan. Masalah umum mencakup menambahkan atau menghilangkan subdomain yang tidak perlu dan menggunakan protokol HTTP yang salah.

Error

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

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

Berhasil

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

Asal ini dapat dinavigasi secara publik.

Jika asal yang diminta adalah versi yang dapat dijelajahi, error ini juga dapat terjadi jika asal memiliki jumlah sampel yang tidak memadai. Semua asal 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 cara situs disertakan dalam set data.

Membuat kueri data URL

Anda telah melihat cara membuat kueri CrUX API untuk pengalaman pengguna secara keseluruhan 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 origin, 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
        }
      },
      // ...
    }
  }
}

Sesuai dengan bentuknya, hasil menunjukkan bahwa https://web.dev/fast/ memiliki 85% pengalaman LCP "baik" dan persentil ke-75 sebesar 1.947 milidetik, yang sedikit lebih baik daripada distribusi di seluruh origin.

Normalisasi URL

CrUX API dapat melakukan normalisasi pada URL yang diminta agar lebih cocok dengan daftar URL yang diketahui. Misalnya, membuat 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 lebih lanjut normalisasi URL di dokumentasi CrUX.

Kueri menurut faktor bentuk

Istilah penting: Faktor bentuk adalah jenis perangkat yang digunakan pengguna untuk mengunjungi situs. Jenis perangkat yang umum mencakup desktop, ponsel, dan tablet.

Pengalaman pengguna dapat bervariasi secara signifikan bergantung pada pengoptimalan situs, kondisi jaringan, dan perangkat pengguna. Untuk lebih memahami perbedaan ini, lihat perincian performa origin dan URL 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 pada pengalaman pengguna tersebut. Contoh ini menunjukkan cara membuat kueri API menurut 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 CrUX API guna mendapatkan data khusus faktor bentuk 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 respons akan memunculkan kembali konfigurasi permintaan formFactor untuk mengonfirmasi bahwa hanya pengalaman ponsel yang disertakan.

Perhatian: Makin terperinci permintaannya, misalnya kombinasi URL dan faktor bentuk tertentu, makin sedikit pengalaman pengguna yang akan disertakan. Hal ini dapat menyebabkan error "tidak ditemukan" lebih sering terjadi, terutama saat membuat kueri URL yang kurang populer atau jenis perangkat tablet yang kurang populer.

Ingat dari bagian sebelumnya bahwa 85% pengalaman pengguna di halaman ini memiliki LCP "baik". Bandingkan dengan pengalaman khusus ponsel, yang hanya 78% dianggap "baik". Persentil ke-75 juga lebih lambat di antara pengalaman ponsel, naik dari 1.947 milidetik menjadi 2.366 milidetik. Segmen 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/articles/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}).`)
  });
}

Poin penting: API hanya dapat dipanggil dengan satu origin atau URL pada satu waktu. Untuk menilai beberapa situs atau halaman, lakukan panggilan terpisah ke API.

Hasilnya menunjukkan bahwa halaman ini lulus penilaian Data Web Inti 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 bahwa pengalaman pengguna sebenarnya 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 hanyalah sebagian kecil dari jenis insight yang dapat diperoleh dengan CrUX. Pengguna set data CrUX di BigQuery mungkin sudah terbiasa dengan beberapa fitur lanjutan, 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 mendetail
  • persentil lainnya

Lihat dokumen CrUX API resmi untuk mendapatkan kunci API Anda dan menjelajahi lebih banyak contoh aplikasi. Kami harap Anda akan mencobanya dan kami ingin mendengar pertanyaan atau masukan yang mungkin Anda miliki. Jadi, hubungi kami di forum diskusi CrUX. Selain itu, untuk terus mendapatkan informasi terbaru tentang semua yang telah kami rencanakan untuk CrUX API, berlanggananlah ke forum pengumuman CrUX atau ikuti kami di Twitter di @ChromeUXReport.