CrUX API nasıl kullanılır?

Milyonlarca web sitesindeki gerçek kullanıcı deneyimi verilerine erişmek için Chrome UX Report API'yi nasıl kullanacağınızı öğrenin.

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

Chrome UX Report (CrUX) veri kümesi, gerçek dünyadaki Chrome kullanıcılarının web'deki popüler hedeflerde nasıl deneyimler yaşadığını gösterir. Sorgulanabilir veri kümesinin BigQuery'de ilk kez kullanıma sunulduğu 2017'den bu yana CrUX'taki alan verileri PageSpeed Insights, CrUX Kontrol Paneli ve Search Console'un Core Web Vitals raporu gibi geliştirici araçlarına entegre edildi. Bu sayede geliştiriciler gerçek kullanıcı deneyimlerini ölçebilir ve izleyebilir. Tüm bu süre boyunca eksik olan şey, CrUX verilerine programatik olarak ücretsiz ve RESTful erişim sağlayan bir araçtı. Bu boşluğu doldurmaya yardımcı olmak için yepyeni Chrome Kullanıcı Deneyimi Raporu API'sinin kullanıma sunulduğunu duyurmaktan mutluluk duyuyoruz.

Bu API, geliştiricilere CrUX verilerine basit, hızlı ve kapsamlı erişim sağlamak amacıyla oluşturulmuştur. CrUX API, Lighthouse performans denetimlerinden elde edilen laboratuvar verilerini de raporlayan mevcut PageSpeed Insights API'nin aksine yalnızca alan kullanıcı deneyimi verilerini raporlar. CrUX API, basitleştirilmiştir ve kullanıcı deneyimi verilerini hızlı bir şekilde sunabilir. Bu da API'yi gerçek zamanlı denetim uygulamaları için ideal hale getirir.

CrUX API, geliştiricilerin en önemli metriklerin tümüne (Core Web Vitals) erişebilmesini sağlamak için Largest Contentful Paint (LCP), Interaction to Next Paint (INP) ve Cumulative Layout Shift'i (CLS) hem kaynak hem de URL düzeyinde denetler ve izler.

Şimdi bu aracı nasıl kullanacağınızı öğrenelim.

Bu sayfada API'yi deneyin

Deneyin.

Kaynak verilerini sorgulama

CrUX veri kümesindeki kaynaklar, temeldeki tüm sayfa düzeyindeki deneyimleri kapsar. Aşağıdaki örnekte, komut satırında cURL kullanılarak bir kaynağın kullanıcı deneyimi verileri için CrUX API'nin nasıl sorgulandığı gösterilmektedir.

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"}'

curl komutu üç bölümden oluşur:

  1. Arayanın özel API anahtarı da dahil olmak üzere API'nin URL uç noktası.
  2. İstek metninin JSON içerdiğini belirten Content-Type: application/json başlığı.
  3. https://web.dev kaynağını belirten JSON kodlamalı istek gövdesi.

Aynı işlemi JavaScript'te yapmak için API çağrısını yapan ve kodu çözülmüş yanıtı döndüren CrUXApiUtil yardımcı programını kullanın (Geçmiş ve toplu destek gibi daha fazla özellik için GitHub varyantımıza da bakın).

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;
  });
};

[YOUR_API_KEY] yerine anahtarınızı yazın. Ardından CrUXApiUtil.query işlevini çağırın ve isteği gövdesini nesneyi iletin.

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

Bu kaynak için veri varsa API yanıtı, kullanıcı deneyimlerinin dağılımını temsil eden metrikler içeren JSON kodlu bir nesnedir. Dağıtım metrikleri, histogram bölmelerini ve yüzdelik dilimleri içerir.

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

histogram nesnesinin start ve end özellikleri, kullanıcıların belirli bir metrik için deneyimlediği değer aralığını temsil eder. density mülkü, bu aralıktaki kullanıcı deneyimlerinin oranını temsil eder. Bu örnekte, tüm web.dev sayfalarındaki LCP kullanıcı deneyimlerinin% 79'u 2.500 milisaniyenin altındadır. Bu, "iyi" LCP eşiğidir. percentiles.p75 değeri,bu dağılımdaki kullanıcı deneyimlerinin% 75'inin 2.216 milisaniyeden kısa olduğu anlamına gelir. Yanıt yapısı hakkında daha fazla bilgiyi yanıt gövdesi dokümanlarında bulabilirsiniz.

Hatalar

CrUX API'de belirli bir kaynak için veri yoksa JSON kodlu bir hata mesajıyla yanıt verilir:

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

Bu hatayı gidermek için öncelikle istenen kaynağın herkese açık olarak gezinilebilir olup olmadığını kontrol edin. Bunu test etmek için tarayıcınızın adres çubuğuna kaynağı girip yönlendirmelerden sonra nihai URL ile karşılaştırabilirsiniz. Sık karşılaşılan sorunlar arasında alt alan adını gereksiz yere ekleme veya atlama ve yanlış HTTP protokolünü kullanma yer alır.

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

Bu kaynak, http:// protokolünü ve www. alt alanını hatalı bir şekilde içeriyor.

Başarılı
{"origin": "https://web.dev"}

Bu kaynak herkese açık olarak gezinilebilir.

İstenen kaynak, gezinilebilir sürüm ise kaynakta yeterli sayıda örnek yoksa da bu hata oluşabilir. Veri kümesine dahil edilen tüm kaynaklarda ve URL'lerde, tekil kullanıcıları anonimleştirmek için yeterli sayıda örnek bulunmalıdır. Ayrıca, kaynaklar ve URL'ler herkese açık olarak dizine eklenebilmelidir. Web sitelerinin veri kümesine nasıl dahil edildiği hakkında daha fazla bilgi edinmek için CrUX metodolojisine göz atın.

URL verilerini sorgulama

Bir kaynaktaki genel kullanıcı deneyimi için CrUX API'yi nasıl sorgulayacağınızı gördünüz. Sonuçları belirli bir sayfayla kısıtlamak için url istek parametresini kullanın.

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/"}'

Bu cURL komutu, kaynak örneğine benzer. Tek fark, istek gövdesinde aranacak sayfayı belirtmek için url parametresinin kullanılmasıdır.

JavaScript'te CrUX API'den URL verilerini sorgulamak için istek gövdesinde url parametresini kullanarak CrUXApiUtil.query işlevini çağırın.

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

CrUX veri kümesinde bu URL'ye ait veriler varsa API, JSON kodlamalı bir yanıt döndürür. Örneğin:

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

Sonuçlar, https://web.dev/fast/'ün %85 oranında "iyi" LCP deneyimine sahip olduğunu ve 1.947 milisaniyelik bir 75. yüzdelik dilime sahip olduğunu gösteriyor. Bu, kaynak genelindeki dağılımın biraz üzerinde.

URL normalleştirme

CrUX API, istenen URL'leri bilinen URL'lerin listesiyle daha iyi eşleşecek şekilde normalleştirebilir. Örneğin, https://web.dev/fast/#measure-performance-in-the-field URL'si için sorgu gönderdiğinizde normalleştirme nedeniyle https://web.dev/fast/ URL'sine ait veriler döndürülür. Bu durumda yanıta bir urlNormalizationDetails nesnesi eklenir.

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

CrUX belgelerinde URL normalleştirme hakkında daha fazla bilgi edinin.

Form faktörüne göre sorgu

Kullanıcı deneyimleri, web sitesi optimizasyonlarına, ağ koşullarına ve kullanıcıların cihazlarına bağlı olarak önemli ölçüde değişiklik gösterebilir. Bu farklılıkları daha iyi anlamak için CrUX API'nin formFactor boyutunu kullanarak kaynak ve URL performansını ayrıntılı olarak inceleyin.

API, üç açık form faktörü değerini destekler: DESKTOP, PHONE ve TABLET. Sonuçları yalnızca bu kullanıcı deneyimleriyle kısıtlamak için kaynak veya URL'ye ek olarak istekte bulunan öğede bu değerlerden birini belirtin. Bu örnekte, cURL kullanılarak API'nin form faktörüne göre nasıl sorgulandığı gösterilmektedir.

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"}'

JavaScript kullanarak form faktörüne özgü veriler için CrUX API'yi sorgulamak istiyorsanız istek gövdesinde url ve formFactor parametrelerini kullanarak CrUXApiUtil.query işlevini çağırın.

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

formFactor parametresinin atlanması, tüm form faktörleri için birleştirilmiş veriler istemeye eşdeğerdir.

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

Yanıtın key alanında, yalnızca telefon deneyimlerinin dahil edildiğini onaylamak için formFactor istek yapılandırması geri yansıtılır.

Önceki bölümde, bu sayfadaki kullanıcı deneyimlerinin% 85'inin "iyi" LCP'ye sahip olduğunu belirtmiştik. Bu oran, yalnızca% 78'inin "iyi" olarak değerlendirildiği telefona özgü deneyimlerle karşılaştırılabilir. Telefon deneyimlerinde 75. yüzdelik dilim de yavaşladı. Bu süre 1.947 milisaniyeden 2.366 milisaniyeye yükseldi. Form faktörüne göre segmentlere ayırma, kullanıcı deneyimlerindeki daha uç eşitsizlikleri vurgulayabilir.

Core Web Vitals performansını değerlendirme

Core Web Vitals programı, bir kullanıcı deneyiminin veya deneyim dağılımının "iyi" olarak kabul edilip edilemeyeceğini belirlemeye yardımcı olan hedefler tanımlar. Aşağıdaki örnekte, bir web sayfasının Core Web Vitals metriklerinin (LCP, INP, CLS) dağılımının "iyi " olup olmadığını değerlendirmek için CrUX API'yi ve CrUXApiUtil.query işlevini kullanıyoruz.

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}).`)
  });
}

Sonuçlar, bu sayfanın üç metrik için de Core Web Vitals değerlendirmelerini geçtiğini gösteriyor.

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

API sonuçlarını izlemenin otomatik bir yoluyla birlikte CrUX'tan alınan veriler, gerçek kullanıcı deneyimlerinin hızlı olmasını ve hızlı kalmasını sağlamak için kullanılabilir. Core Web Vitals ve bunların nasıl ölçüldüğü hakkında daha fazla bilgi için Web Vitals ve Core Web Vitals'ı ölçme araçları başlıklı makalelere göz atın.

Sırada ne var?

CrUX API'nin ilk sürümünde yer alan özellikler, CrUX ile elde edebileceğiniz analiz türlerinin yalnızca bir kısmını kapsar. BigQuery'deki CrUX veri kümesini kullananlar aşağıdakiler gibi daha gelişmiş özelliklerden bazılarını biliyor olabilir:

  • Ek metrikler
    • first_paint
    • dom_content_loaded
    • onload
    • time_to_first_byte
    • notification_permissions
  • Ek boyutlar
    • month
    • country
    • effective connection type (ECT)
  • Ek ayrıntı düzeyi
    • ayrıntılı histogramlar
    • daha fazla yüzdelik dilim

API anahtarınızı edinmek ve daha fazla örnek uygulamayı keşfetmek için resmi CrUX API dokümanlarına göz atın. Bu özelliği denemenizi umuyoruz. Sorularınız veya geri bildirimleriniz varsa CrUX tartışma forumundan bize ulaşabilirsiniz. CrUX API için planladığımız her şeyden haberdar olmak istiyorsanız CrUX duyuru forumuna abone olun veya Twitter'da @ChromeUXReport adresinden bizi takip edin.