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 yaşadığı deneyimleri gösterir. Sorgulanabilir veri kümesi 2017'de ilk kez BigQuery'de yayınlandığından beri CrUX'taki alan verileri, PageSpeed Insights ve Search Console'un Core Web Vitals raporu gibi geliştirici araçlarına entegre edilerek geliştiricilerin gerçek kullanıcı deneyimlerini ölçüp izlemesine olanak tanıyor. Bu zamana kadar eksik olan şey, CrUX verilerine programatik olarak ücretsiz ve RESTful erişim sağlayan bir araçtı. Bu açığı kapatmaya yardımcı olmak için yepyeni Chrome Kullanıcı Deneyimi Raporu API'sinin kullanıma sunulduğunu duyurmaktan heyecan duyuyoruz.

Bu API, geliştiricilere CrUX verilerine 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, kolaylaştırılmış bir yapıya sahiptir ve kullanıcı deneyimi verilerini hızlı bir şekilde sunabilir. Bu nedenle, gerçek zamanlı denetim uygulamaları için idealdir.

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

Haydi, bu aracı nasıl kullanacağımızı öğrenelim.

Bu sayfada API'yi deneyin

Deneyin.

Sorgu kaynağı verileri

CrUX veri kümesindeki kaynaklar, temel alınan tüm sayfa düzeyindeki deneyimleri kapsar. Aşağıdaki örnekte, komut satırında curl kullanarak bir kaynağın kullanıcı deneyimi verileri için CrUX API'sinin nasıl sorgulanacağı 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 gövdesinin JSON içerdiğini belirten Content-Type: application/json üstbilgisi.
  3. https://web.dev kaynağını belirten, JSON biçiminde kodlanmış istek gövdesi.

Aynı işlemi JavaScript'te yapmak için CrUXApiUtil yardımcı programını kullanın. Bu yardımcı program, API çağrısı yapar ve kodlanmış yanıtı döndürür (geçmiş ve toplu destek gibi daha fazla özellik için GitHub varyantımıza da göz atı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] kısmını anahtarınızla değiştirin. Ardından, CrUXApiUtil.query işlevini çağırın ve istek gövdesi nesnesini 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ı gösteren metrikler içeren JSON kodlu bir nesnedir. Dağıtım metrikleri, histogram bölmeleri ve yüzdelik dilimlerdir.

{
  "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 metrik için deneyimlediği değer aralığını temsil eder. density özelliği, bu aralıktaki kullanıcı deneyimlerinin oranını gösterir. Bu örnekte, tüm web.dev sayfalarındaki LCP kullanıcı deneyimlerinin% 79'u 2.500 milisaniyenin altında. Bu değer, "iyi" LCP eşiğidir. percentiles.p75 değeri,bu dağıtı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 belgelerinde bulabilirsiniz.

Hatalar

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

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

Bu hatayı ayıklamak için öncelikle istenen kaynağın herkese açık olarak gezinilebilir olup olmadığını kontrol edin. Bunu, kaynağı tarayıcınızın adres çubuğuna girip yönlendirmelerden sonra nihai URL ile karşılaştırarak test edebilirsiniz. Yaygın sorunlar arasında alt alan adının gereksiz yere eklenmesi veya çıkarılması ve yanlış HTTP protokolünün kullanılması yer alır.

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

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

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

Bu kaynak herkese açık olarak gezilebilir.

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

URL verilerini sorgulama

Bir kaynakta genel kullanıcı deneyimi için CrUX API'sini nasıl sorgulayacağınızı öğrendiniz. 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 ancak istek gövdesinde aranacak sayfayı belirtmek için url parametresi kullanılır.

JavaScript'te CrUX API'den URL verilerini sorgulamak için istek gövdesindeki 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);
});

Bu URL'ye ait veriler CrUX veri kümesinde varsa API, JSON kodlu 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ın %85 "iyi" LCP deneyimine ve 1.947 milisaniyelik yüzde 75'lik dilime sahip olduğunu gösteriyor. Bu değer, kaynak genelindeki dağılımdan biraz daha iyi.

URL normalleştirme

CrUX API, bilinen URL'ler listesiyle daha iyi eşleşmesi için istenen URL'leri normalleştirebilir. Örneğin, https://web.dev/fast/#measure-performance-in-the-field URL'si için yapılan sorgu, normalleştirme nedeniyle https://web.dev/fast/ URL'siyle ilgili verilerle sonuçlanı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 belgelerinden 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şebilir. 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 sınırlamak için kaynak veya URL'ye ek olarak istek gövdesinde bu değerlerden birini belirtin. Bu örnekte, curl kullanarak API'ye form faktörüne göre nasıl sorgu gönderileceği 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 üzere 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ş verilerin istenmesine 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ı, yalnızca telefon deneyimlerinin dahil edildiğini onaylamak için formFactor istek yapılandırmasını tekrar gösterir.

Önceki bölümden hatırlayacağınız gibi, bu sayfadaki kullanıcı deneyimlerinin% 85'inde "iyi" LCP vardı. Bunu, yalnızca% 78'inin "iyi" olarak kabul edildiği telefona özel deneyimlerle karşılaştırın. 75. yüzdelik dilim de telefon deneyimlerinde daha yavaş olup 1.947 milisaniyeden 2.366 milisaniyeye yükseldi. Biçim faktörüne göre segmentasyon, kullanıcı deneyimlerindeki daha uç farklılıkları vurgulayabilir.

Core Web Vitals performansını değerlendirme

Önemli Web Verileri 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ğıtı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/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}).`)
  });
}

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

CrUX'tan alınan veriler, API sonuçlarını izlemek için otomatik bir yöntemle birlikte kullanılarak 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çüleceği hakkında daha fazla bilgi için Web Vitals ve Core Web Vitals'ı ölçmeye yönelik araçlar sayfalarına göz atın.

Sırada ne var?

CrUX API'nin ilk sürümünde yer alan özellikler, CrUX ile elde edilebilecek analizlerin yalnızca bir kısmını kapsar. BigQuery'deki CrUX veri kümesinin kullanıcıları, aşağıdakiler de dahil olmak üzere bazı gelişmiş özelliklere aşina olabilir:

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

API anahtarınızı edinmek ve daha fazla örnek uygulamayı incelemek için resmi CrUX API dokümanlarına göz atın. Özelliği deneyeceğinizi umuyoruz. Sorularınız veya geri bildirimleriniz olursa CrUX tartışma forumunda 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.