Cara menggunakan CrUX API

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

Rick Viscomi

Shane Exterkamp

Set data Chrome UX Report (CrUX) merepresentasikan cara pengguna Chrome di dunia nyata merasakan 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 dalam alat developer seperti PageSpeed Insights, Dasbor CrUX, dan laporan Data Web Inti Search Console, memungkinkan developer mengukur dan memantau pengalaman pengguna yang sebenarnya. Bagian yang hilang 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 perilisan Chrome UX Report API yang baru.

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

Untuk memastikan developer memiliki akses ke semua metrik yang paling penting—Core Web Vitals—CruUX API mengaudit dan memantau Largest Contentful Paint (LCP), First Input Delay (FID), dan Kumulatif Layout Shift (CLS) di tingkat origin dan URL.

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

Data asal kueri

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 pada 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 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 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 metrics yang mewakili distribusi pengalaman pengguna. Metrik distribusi adalah kelompok dan persentil histogram.

{
  "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 mewakili 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 batas LCP "baik". Nilai percentiles.p75 berarti 75% pengalaman pengguna dalam distribusi ini berdurasi kurang dari 2.216 milidetik. Pelajari lebih lanjut struktur respons dalam dokumentasi isi respons.

Error

Jika tidak memiliki data untuk asal 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, terlebih dahulu periksa apakah origin yang diminta dapat dijelajahi secara publik. Anda dapat mengujinya dengan memasukkan origin ke kolom URL browser dan membandingkannya dengan URL final setelah pengalihan apa pun. Masalah umum termasuk menambahkan atau menghilangkan subdomain dan menggunakan protokol HTTP yang salah secara tidak perlu.

Error

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

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

Berhasil

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

Asal ini dapat dijelajahi secara publik.

Jika origin yang diminta adalah versi yang dapat dijelajahi, 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 pengguna perorangan. Selain itu, origin dan URL harus dapat diindeks secara publik. Lihat metodologi CrUX untuk mempelajari lebih lanjut cara situs disertakan dalam set data.

Data URL kueri

Anda telah mengetahui cara membuat kueri CrUX API untuk keseluruhan pengalaman pengguna di suatu tempat asal. 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
        }
      },
      // ...
    }
  }
}

Benar, hasilnya menunjukkan bahwa https://web.dev/fast/ memiliki 85% pengalaman LCP "baik" dan persentil ke-75 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 diketahui. Misalnya, pembuatan 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 dalam dokumentasi CrUX.

Kueri menurut faktor bentuk

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

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

API ini mendukung tiga nilai faktor bentuk eksplisit: DESKTOP, PHONE, dan TABLET. Selain origin atau URL, tentukan salah satu nilai ini dalam 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"}'

Guna membuat kueri CrUX API untuk 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 di respons akan menampilkan kembali konfigurasi permintaan formFactor untuk mengonfirmasi bahwa hanya pengalaman ponsel yang disertakan.

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

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

Menilai performa Data Web Inti

Program Data Web Inti menentukan target yang membantu menentukan apakah pengalaman pengguna atau distribusi pengalaman dapat dianggap "baik". Dalam contoh berikut, kita menggunakan CrUX API dan fungsi CrUXApiUtil.query untuk menilai apakah distribusi metrik Data Web Inti (LCP, FID, CLS) di 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',
    'first_input_delay',
    '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 tersebut.

The 75th percentile (1973) of largest_contentful_paint passes the Core Web Vitals "good" threshold (2500).
The 75th percentile (20) of first_input_delay passes the Core Web Vitals "good" threshold (100).
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 mengetahui informasi selengkapnya tentang Data Web Inti dan cara mengukurnya, lihat Data Web dan Alat untuk mengukur Data Web Inti.

Apa langkah selanjutnya?

Fitur yang disertakan dalam versi awal CrUX API hanya menjelaskan jenis insight yang dapat diperoleh dengan CrUX. Pengguna set data CrUX di BigQuery mungkin sudah mengenal 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 lebih banyak

Lihat dokumen CrUX API resmi untuk mendapatkan kunci API Anda dan mempelajari aplikasi contoh lainnya. Kami harap Anda akan mencobanya dan kami ingin mendengar pertanyaan atau masukan yang mungkin Anda miliki. Jadi, hubungi kami di forum diskusi CrUX. Dan untuk terus mendapatkan info terbaru mengenai semua yang kami rencanakan untuk CrUX API, berlanggananlah ke forum pengumuman CrUX atau ikuti kami di Twitter di @ChromeUXReport.