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

CrUX API nasıl kullanılır?

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

Rick Viscomi

Shane Exterkamp

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ümesi BigQuery'de ilk kez kullanıma sunulduğu 2017 yılından beri CrUX'teki 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çüp 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 doldurmak için yeni Chrome UX Report API'nin kullanıma sunulduğunu bildirmekten mutluluk duyuyoruz.

Bu API, geliştiricilere CrUX verilerine basit, hızlı ve kapsamlı erişim sağlamak amacıyla tasarlanmıştır. 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. Kolay kullanılabilen ve kullanıcı deneyimi verilerini hızla sunabilen CrUX API, gerçek zamanlı denetim uygulamaları için ideal bir çözümdür.

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

Şimdi başlayalım ve nasıl kullanılacağını görelim.

Sorgu kaynak verileri

CrUX veri kümesindeki kaynaklar, temelde yatan 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'nin 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"}'

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ılmıştır. CrUX API belgeleri bölümünde 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 üst bilgisi.
https://web.dev kaynağını belirten JSON kodlu istek gövdesi.

Aynı şeyi JavaScript'te yapmak için CrUXApiUtil yardımcı programını kullanın, API çağrısında bulunan ve kodu çözülmüş yanıtı döndürür (GitHub varyantımıza da bakın) daha fazla özellik için (geçmiş ve toplu destek dahil) 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. Daha sonra, CrUXApiUtil.query işlevini çağırın ve request body 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 metrikler içeren JSON kodlu bir nesnedir. Dağılı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 bir metrik için deneyimlediği 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ında. Bu da "iyi"dir. LCP eşiği. percentiles.p75 değeri,bu dağılımdaki kullanıcı deneyimlerinin% 75'inin 2.216 milisaniyeden az 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 kodlu bir hata mesajıyla yanıt verir:

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

Bu hatanın hatalarını ayıklamak için önce istenen kaynağın herkese açık olup olmadığını kontrol edin. Kaynak URL'yi tarayıcınızın adres çubuğuna girip herhangi bir yönlendirmeden sonraki nihai URL ile karşılaştırarak bunu test edebilirsiniz. Genel sorunlar arasında alt alan adının gereksiz şekilde eklenmesi veya çıkarılması ve yanlış HTTP protokolünün kullanılması bulunur.

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 kaynakta herkes tarafından gezinilebilir.

İstenen kaynak gezinilebilir sürüm ise ve kaynakta yetersiz örnek sayısı olduğunda da bu hata oluşabilir. Veri kümesine dahil edilen tüm kaynaklar ve URL'ler, bağımsız kullanıcıların anonimleştirilmesi 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 metodolojisine bakın.

Sorgu URL'si verileri

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 sınırlamak 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övdesinin aranacak sayfayı belirtmek için url parametresini kullanmasıdı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'nin verileri CrUX veri kümesindeyse 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
        }
      },
      // ...
    }
  }
}

Forma göre, sonuçlar https://web.dev/fast/ için %85 "iyi" olduğunu gösteriyor LCP deneyimleri ve 1.947 milisaniyelik 75. yüzdelik dilim değeri, 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/ verileriyle 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"
  }
}

URL normalleştirme hakkında daha fazla bilgiye CrUX belgelerinden ulaşabilirsiniz.

Form faktörüne göre sorgu

Kullanıcı deneyimleri; web sitesi optimizasyonlarına, ağ koşullarına ve kullanıcıların deneyimlerine cihazlar. 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. Kaynak veya URL'ye ek olarak, sonuçları yalnızca bu kullanıcı deneyimleriyle kısıtlamak için 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 için birlikte veri 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ı, yalnızca telefon deneyimlerinin dahil edildiğini onaylamak için formFactor istek yapılandırmasını tekrarlar.

Önceki bölümden, bu sayfadaki kullanıcı deneyimlerinin% 85'inin "iyi" olduğunu hatırlayın LCP Bunu, yalnızca% 78'inin "iyi" olarak değerlendirildiği telefona özgü deneyimlerle karşılaştırın. 75. yüzdelik dilim de telefon deneyimlerinde 1.947 milisaniyeden 2.366 milisaniyeye kadar daha yavaştır. Form faktörüne göre segmentlere ayırma, kullanıcı deneyimlerinde daha aşırı farklılıkları öne çıkarma potansiyeline sahiptir.

Core Web Vitals performansını değerlendirin

Core Web Vitals 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 Core Web Vitals metrikleri (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 üç metriğin tamamı için 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 verileri, API sonuçlarını izlemek için otomatik bir yöntemle bir araya getirildiğinde, gerçek kullanıcı deneyimlerinin hızlanması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 Verileri'ne ve Core Web Vitals'ı ölçme araçları'na göz atın.

Sırada ne var?

CrUX API'nin ilk sürümünde yer alan özellikler, CrUX ile elde edilebilecek analiz türlerinin yalnızca yüzeysel bir kısmını oluşturur. BigQuery'deki CrUX veri kümesi kullanıcıları, aşağıdakiler de dahil olmak üzere daha gelişmiş özelliklerden bazılarına aşina 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ı edinmek ve diğer örnek uygulamaları keşfetmek için resmi CrUX API belgelerine 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 ile ilgili olarak planladığımız her şeyden haberdar olmak için CrUX duyuru forumuna abone olun veya bizi Twitter'da @ChromeUXReport adresinden takip edin.