Bu sayfa, Cloud Translation API ile çevrilmiştir.

CrUX API nasıl kullanılır?

Milyonlarca web sitesinde 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

Chrome Kullanıcı Deneyimi Raporu (CrUX) veri kümesi, gerçek Chrome kullanıcılarının web'deki popüler yerlerle ilgili deneyimleri hakkında bilgi verir. Sorgulanabilir veri kümesinin BigQuery'de ilk kullanıma sunulduğu 2017'den beri, CrUX'ten alınan alan verileri PageSpeed Insights, CrUX Kontrol Paneli ve Search Console'un Önemli Web Verileri raporu gibi geliştirici araçlarına entegre edilmiştir. Bu sayede geliştiriciler, gerçek kullanıcı deneyimlerini ölçebilir ve izleyebilir. Bu süre boyunca eksik olan şey, CrUX verilerine programatik olarak ücretsiz ve RESTful erişim sağlayan bir araç oldu. Bu boşluğu doldurmaya 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 basit, hızlı ve kapsamlı erişim sağlamak amacıyla oluşturulmuştur. Lighthouse performans denetimlerindeki laboratuvar verilerini de bildiren mevcut PageSpeed Insights API'nin aksine CrUX API yalnızca alan kullanıcı deneyimi verilerini raporlar. Kolaylaştırılmış CrUX API, kullanıcı deneyimi verilerini hızlı bir şekilde sunabilir ve gerçek zamanlı denetim uygulamaları için idealdir.

Geliştiricilerin en önemli metriklere (Core Web Vitals) erişebildiğinden emin olmak için CrUX API, Largest Contentful Paint (LCP), First Input Delay (FID) ve Cumulative Layout Shift'i (CLS) hem kaynak hem de URL düzeyinde denetler ve izler.

Öyleyse başlayalım ve nasıl kullanılacağına bakalım!

Sorgu kaynak verileri

CrUX veri kümesindeki kaynaklar, sayfa düzeyindeki temel deneyimlerin tümünü kapsar. Aşağıdaki örnek, komut satırında cURL kullanarak bir kaynağın kullanıcı deneyimi verileri için CrUX API'nin nasıl sorgulanacağını göstermektedir.

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

Not: Tüm API istekleri, key parametresi için bir değer sağlamalıdır. Önceki örnekte [YOUR_API_KEY] yer tutucu olarak bırakılır. CrUX API dokümanlarında açıklandığı şekilde kendi özel CrUX API anahtarınızı alın.

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

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

JavaScript'te aynı şeyi yapmak için CrUXApiUtil yardımcı programını kullanın. Bu yardımcı program, API çağrısında bulunur ve kodu çözülmüş yanıtı döndürür (geçmiş ve toplu destek de dahil olmak üzere 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] öğesini kendi anahtarınızla değiştirin. Daha sonra, 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 mevcutsa API yanıtı, kullanıcı deneyimlerinin dağılımını temsil eden metrics içeren JSON kodlamalı bir nesnedir. Dağılım metrikleri histogram kutuları ve yüzdeliktir.

{
  "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, belirli bir metrik için kullanıcıların yaşadığı değer aralığını temsil eder. density özelliği, 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 gövdesi dokümanlarında yanıt yapısı hakkında daha fazla bilgi edinebilirsiniz.

Hatalar

CrUX API belirli bir kaynak için herhangi bir veriye sahip olmadığında JSON kodlamalı bir hata mesajıyla yanıt verir:

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

Bu hatada hata ayıklamak için öncelikle istenen kaynakta herkese açık şekilde gezinilebilir olup olmadığını kontrol edin. Bunu, kaynağı tarayıcınızın adres çubuğuna girip herhangi bir yönlendirmeden sonra nihai URL ile karşılaştırarak test edebilirsiniz. Alt alan adının gereksiz yere eklenmesi veya atlanması ve yanlış HTTP protokolünün kullanılması sık karşılaşılan sorunlar arasındadır.

Hata

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

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

Başarılı

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

Bu kaynak herkese açık olarak gezinilebilir.

İstenen kaynak gezinilebilir sürüm ise bu hata, kaynakta yeterli sayıda örnek olmadığında da bu hata oluşabilir. Veri kümesindeki tüm kaynaklar ve URL'ler, tekil kullanıcıları anonimleştirmek için yeterli sayıda örneğe sahip olmalıdır. 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 metodolojisini inceleyin.

Sorgu URL'si verileri

Bir kaynakta genel kullanıcı deneyimi için CrUX API'nin nasıl sorgulanacağını 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, istek gövdesinin aranacak sayfayı belirtmek için url parametresini kullanması dışında kaynak örneğine benzer.

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

Bu URL'nin verileri CrUX veri kümesinde mevcutsa 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/ ürününün %85 "iyi" LCP deneyimlerine ve 1.947 milisaniyelik 75. yüzde birliğe sahip olduğunu gösteriyor. Bu, kaynak genelindeki dağılımdan biraz daha iyidir.

URL normalleştirmesi

CrUX API, istenen URL'leri bilinen URL'ler listesiyle daha iyi eşleşecek şekilde normalleştirebilir. Örneğin, https://web.dev/fast/#measure-performance-in-the-field URL'sinin sorgulanması, normalleştirme nedeniyle https://web.dev/fast/ verilerinin görüntülenmesine neden olur. 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 dokümanlarından URL normalleştirmesi hakkında daha fazla bilgi edinebilirsiniz.

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 farklılık 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 olan üç 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 istek gövdesinde bu değerlerden birini belirtin. Bu örnekte, cURL kullanılarak API'nin form faktörüne göre 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 '{"url": "https://web.dev/fast/", "formFactor": "PHONE"}'

JavaScript kullanarak form faktörüne özel veriler için CrUX API'yi sorgulamak amacıyla, istek gövdesindeki 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 birlikte için veri istemeyle 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ı geri döndürür.

Önceki bölümden hatırlayacağınız gibi, bu sayfadaki kullanıcı deneyimlerinin% 85'i "iyi" LCP'ye sahiptir. Bu oranı, yalnızca% 78'inin "iyi" olarak değerlendirildiği telefona özgü deneyimlerle karşılaştırın. Telefon deneyimlerinde 75. yüzdelik dilim, 1.947 milisaniyeden 2.366 milisaniyeye yükselerek daha yavaştır. Form faktörüne göre segmentlere ayırma, kullanıcı deneyimlerindeki daha uç noktalardaki eşitsizlikleri öne çıkarma potansiyeline sahiptir.

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 edilmeyeceğini belirlemeye yardımcı olan hedefleri tanımlar. Aşağıdaki örnekte, bir web sayfasının Önemli Web Verileri metriklerinin (LCP, FID, CLS) dağılımının "iyi" olup olmadığını değerlendirmek için CrUX API ve CrUXApiUtil.query işlevi kullanılmıştır.

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

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

API sonuçlarının otomatik olarak izlenmesini sağlayan bir yöntemle birlikte, CrUX verileri, gerçek kullanıcı deneyimlerinin hızla 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 edinmek için Web Vitals ve Core Web Vitals'ı ölçen araçlar sayfalarına göz atın.

Sonraki adım

CrUX API'nin ilk sürümünde yer alan özellikler, yalnızca CrUX ile elde edilebilecek analiz türlerinin önünü çizer. BigQuery'deki CrUX veri kümesinin kullanıcıları, aşağıdakiler de dahil olmak üzere daha gelişmiş özelliklerin bazıları hakkında bilgi sahibi olabilir:

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

API anahtarınızı almak ve diğer örnek uygulamaları keşfetmek için resmi CrUX API belgelerine göz atın. Özelliği deneyeceğinizi umuyoruz. Sorularınız veya geri bildirimleriniz olursa lütfen CrUX tartışma forumundan bize ulaşın. CrUX API için planladığımız her şeyden haberdar olmak için CrUX duyuru forumuna abone olun veya bizi Twitter'da @ChromeUXReport adresinden takip edin.