CrUX API'si

CrUX API, sayfa ve kaynak ayrıntı düzeyinde birleştirilmiş gerçek kullanıcı deneyimi verilerine düşük gecikmeli erişim sağlar.

Yaygın kullanım alanı

CrUX API, "https://example.com kaynağı için metrikleri al" gibi belirli bir URI için kullanıcı deneyimi metriklerinin sorgulanmasına olanak tanır.

CrUX API Anahtarı

CrUX API'yi kullanmak için Google Cloud API anahtarı gerekir. Kimlik bilgileri sayfasında bir tane oluşturabilir ve Chrome UX Report API kullanımı için bunun temel hazırlığını yapabilirsiniz.

Bir API anahtarınız olduktan sonra, uygulamanız tüm istek URL'lerine key=[YOUR_API_KEY] sorgu parametresini ekleyebilir. Örnek sorgular bölümüne bakın.

API anahtarı, URL'lere yerleştirmek için güvenlidir; herhangi bir kodlama yapmanız gerekmez.

Veri modeli

Bu bölümde, istekler ve yanıtlardaki verilerin yapısı ayrıntılı olarak açıklanmaktadır.

Kaydet

Bir sayfa veya site hakkında ayrı ayrı bilgiler. Bir kayıt, bir tanımlayıcıya ve belirli bir boyut kombinasyonuna özel veriler içerebilir. Bir kayıt, bir veya daha fazla metriğe ait verileri içerebilir.

Tanımlayıcılar

Tanımlayıcılar, hangi kayıtların aranması gerektiğini belirtir. CrUX'te bu tanımlayıcılar, web sayfaları ve web siteleridir.

Köken

Tanımlayıcı bir kaynak olduğunda, söz konusu kaynaktaki tüm sayfalar için mevcut olan tüm veriler birlikte toplanır. Örneğin, http://www.example.com kaynağında şu site haritasında belirtildiği şekilde sayfalar bulunduğunu varsayalım:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Bu durumda, kaynağı http://www.example.com olarak ayarlanmış Chrome Kullanıcı Deneyimi Raporu sorgulandığında, http://www.example.com/, http://www.example.com/foo.html ve http://www.example.com/bar.html verileri ilgili kaynak altındaki tüm sayfalar olduğundan bu veriler toplu şekilde döndürülür.

URL'ler

Tanımlayıcı bir URL olduğunda, yalnızca söz konusu URL'ye ilişkin veriler döndürülür. http://www.example.com kaynak site haritasına tekrar baktığınızda:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Tanımlayıcı, http://www.example.com/foo.html değeriyle URL olarak ayarlanırsa yalnızca bu sayfaya ait veriler döndürülür.

Boyutlar

Boyutlar, bir kaydın toplandığı belirli bir veri grubunu tanımlar. Örneğin, PHONE form faktörü, kaydın bir mobil cihazda gerçekleşen yüklemelerle ilgili bilgi içerdiğini gösterir. Her boyutta belirli sayıda değer olacaktır ve bu boyutun dolaylı olarak belirtilmemesi, boyutun tüm değerlerden toplandığı anlamına gelir. Örneğin, herhangi bir form faktörü belirtilmesi, kaydın herhangi bir form faktöründe gerçekleşen yüklemelerle ilgili bilgi içerdiğini gösterir.

Form Faktörü

Son kullanıcının sayfaya gitmek için kullandığı cihaz sınıfı. Bu; PHONE, TABLET ve DESKTOP olarak ayrılmış genel bir cihaz sınıfıdır.

Etkili Bağlantı Türü

Etkili Bağlantı Türü, sayfaya giderken cihazın tahmini bağlantı kalitesidir. Bu, offline, slow-2G, 2G, 3G ve 4G olarak bölünen genel bir sınıftır.

Metrik

Metrikler, istatistiksel toplamalar olarak histogram, yüzdelik dilim ve kesir halinde raporlanır.

Kayan nokta değerleri, 4 ondalık basamak olacak şekilde yuvarlanır (cumulative_layout_shift metriklerinin dize olarak iki kez kodlandığını, dolayısıyla kayan nokta olarak değerlendirilmediğini ve dize içinde 2 ondalık basamağa kadar raporlandığını unutmayın).

Histogram

Metrikler histogramda ifade edildiğinde, söz konusu metrik için belirli aralıklara denk gelen sayfa yükleme yüzdelerini gösteririz.

Örnek bir metrik için basit bir üç bin histogramı aşağıdaki gibi görünür:

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

Bu veriler, sayfa yüklemelerinin% 38,18'inde örnek metriğin 0 ms ile 1.000 ms arasında ölçüldüğünü göstermektedir. Metriğin birimleri bu histogramda yer almaz. Bu örnekte, milisaniye değerini kabul edeceğiz.

Buna ek olarak, sayfa yüklemelerinin% 49,91'inde 1.000 ms ile 3.000 ms arasında bir metrik değeri görülürken, %11,92'sinde 3.000 ms'den daha yüksek bir değer görülmüştür.

Yüzdelik dilimler

Metrikler, ek analiz için yararlı olabilecek yüzdelik dilimleri de içerebilir. Belirli metrik değerleri, söz konusu metrik için belirtilen yüzdelik dilimde raporlanır. Bunlar, nihai bağlı verilere değil, kullanılabilir verilerin tamamına dayanır ve bu nedenle, son binlenmiş histograma dayalı interpolasyon yüzdelik dilimle eşleşmezler.

{
  "percentiles": {
    "p75": 2063
  }
}

Bu örnekte, sayfa yüklemelerinin en az% 75'i <= 2063 metrik değeri ile ölçülmüştür.

Kesirler

Kesirler, belirli bir şekilde etiketlenebilecek sayfa yüklemelerinin yüzdelerini gösterir. Bu durumda, metrik değerleri bu etiketlerdir.

Örneğin, form_factors metriği, ilgili sorgunun kapsadığı form faktörlerinin (veya cihazların) dökümünü listeleyen bir fractions nesnesinden oluşur:

"form_factors": {
  "fractions": {
    "desktop": 0.0377,
    "tablet": 0.0288,
    "phone": 0.9335
  }
}

Bu örnekte, sayfa yüklemelerinin% 3,77'si masaüstünde, %2,88'i tablette ve% 93,35'i telefonda ölçülmüştür. Bu, toplamda% 100'dür.

Metrik değeri türleri

CrUX API Metriği Adı	Veri Türü	Metrik Birimleri	İstatistiksel Toplamalar	Belgeler
cumulative_layout_shift	dize olarak çift kodlanmış 2 ondalık basamak	birimsiz	üç bölmeli histogram, p75'li yüzdelik dilimler	cls
first_contentful_paint	int	milisaniye	üç bölmeli histogram, p75'li yüzdelik dilimler
first_input_delay (desteği sonlandırılmış)	int	milisaniye	üç bölmeli histogram, p75'li yüzdelik dilimler	fid
interaction_to_next_paint	int	milisaniye	üç bölmeli histogram, p75'li yüzdelik dilimler	inp
largest_contentful_paint	int	milisaniye	üç bölmeli histogram, p75'li yüzdelik dilimler	lcp
experimental_time_to_first_byte	int	milisaniye	üç bölmeli histogram, p75'li yüzdelik dilimler	ttfb
form_factors	4 ondalık basamak	yüzde	form faktöründen kesirlere eşleme	form faktörleri
navigation_types	4 ondalık basamak	yüzde	gezinme türünden kesirlere eşleme	gezinme türleri
round_trip_time	int	milisaniye	p75'e sahip yüzdelik dilimler	rtt

BigQuery metrik adı eşleme

CrUX API Metriği Adı	BigQuery Metriği Adı
cumulative_layout_shift	layout_instability.cumulative_layout_shift
first_contentful_paint	first_contentful_paint
first_input_delay	first_input.delay
interaction_to_next_paint	interaction_to_next_paint
largest_contentful_paint	largest_contentful_paint
experimental_time_to_first_byte	experimental.time_to_first_byte
navigation_types	navigation_types
form_factors	Yok
round_trip_time	Yok

Toplama dönemi

Ekim 2022 itibarıyla CrUX API, toplama aralığının başlangıç ve bitiş tarihlerini temsil eden firstDate ve endDate alanlarının bulunduğu bir collectionPeriod nesnesi içeriyor. Örneğin:

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }

Bu, verilerin ve söz konusu gün için henüz güncellenip güncellenmediğinin veya düne ait aynı verileri döndürüp döndürülmediğinin daha iyi anlaşılmasını sağlar.

CrUX API'nin, ilgili gün için tamamlanmış verileri beklediği için bugünün tarihinden yaklaşık iki gün geride olduğunu ve API'de kullanılabilmesi için biraz işlem süresi gerektiğini unutmayın. Kullanılan saat dilimi, yaz saati uygulamasında değişiklik yapılmayan Pasifik Standart Saati'dir (PST).

Örnek sorgular

Sorgular, POST gövdesinde JSON nesnesi olarak sorgu verilerine sahip https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" öğesine bir POST isteği kullanılarak JSON nesneleri olarak gönderilir:

{
  "origin": "https://example.com",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

Örneğin bu, aşağıdaki komut satırıyla (API_KEY yerine kendi anahtarınızla) curl konumundan çağrılabilir:

curl -s --request POST 'https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=API_KEY' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --data '{"formFactor":"PHONE","origin":"https://www.example.com","metrics":["largest_contentful_paint", "experimental_time_to_first_byte"]}'

Sayfa düzeyindeki veriler, origin yerine sorguda bir url özelliği iletilerek API aracılığıyla kullanılabilir:

{
  "url": "https://example.com/page",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

metrics özelliği ayarlanmazsa kullanılabilir tüm metrikler döndürülür:

• cumulative_layout_shift
• first_contentful_paint
• first_input_delay (desteği sonlandırılmış)
• interaction_to_next_paint
• largest_contentful_paint
• experimental_time_to_first_byte
• navigation_types
• form_factors (yalnızca istekte formFactor belirtilmediyse raporlanır)

formFactor değeri sağlanmazsa değerler tüm form faktörleri genelinde toplanır.

Daha fazla örnek sorgu için Chrome Kullanıcı Deneyimi Raporu API'sini kullanma bölümüne bakın.

Veri ardışık düzeni

CrUX veri kümesi, API kullanılarak kullanıma sunulmadan önce verileri birleştirmek, toplamak ve filtrelemek için bir ardışık düzen aracılığıyla işlenir.

Hareketli ortalama

Chrome Kullanıcı Deneyimi Raporu'ndaki veriler, toplu metriklerin 28 günlük hareketli ortalamasıdır. Diğer bir deyişle, herhangi bir zamanda Chrome Kullanıcı Deneyimi Raporu'nda sunulan veriler, birleştirilmiş olarak son 28 güne ait verilerdir.

Bu, BigQuery'deki CrUX veri kümesinin aylık raporları toplamasına benzer.

Günlük güncellemeler

Veriler her gün 04:00 UTC civarında güncellenir. Güncelleme zamanları için hizmet düzeyi sözleşmesi yoktur. Bu sözleşme her gün elinden gelenin en iyisi yapılarak gerçekleştirilir.

Şema

CrUX API için, POST HTTP isteğini kabul eden tek bir uç nokta bulunur. API, istenen kaynak veya sayfayla ilgili performans verilerine karşılık gelen bir veya daha fazla metrics içeren bir record döndürür.

HTTP isteği

POST https://chromeuxreport.googleapis.com/v1/records:queryRecord

URL, gRPC Kod Dönüştürme söz dizimini kullanır.

İstek içeriği

İstek gövdesi aşağıdaki yapıya sahip verileri içermelidir:

{
  "effectiveConnectionType": string,
  "formFactor": enum (FormFactor),
  "metrics": [
    string
  ],

  // Union field url_pattern can be only one of the following:
  "origin": string,
  "url": string
  // End of list of possible types for union field url_pattern.
}

Alanlar
effectiveConnectionType	string Etkin bağlantı türü, kayıt verilerinin ait olduğu etkili ağ sınıfını belirten bir sorgu boyutudur. Bu alanda, Network Information API spesifikasyonunda belirtilen ["offline", "slow-2G", "2G", "3G", "4G"] değerleri kullanılır. Not: Etkili bir bağlantı türü belirtilmezse tüm etkin bağlantı türleri üzerinden birleştirilmiş verileri içeren özel bir kayıt döndürülür.
formFactor	enum (FormFactor) Form faktörü, kayıt verilerinin ait olduğu cihaz sınıfını belirten bir sorgu boyutudur. Bu alanda DESKTOP, PHONE veya TABLET değerleri kullanılır. Not: Herhangi bir form faktörü belirtilmezse tüm form faktörleri üzerinde birleştirilmiş verileri içeren özel bir kayıt döndürülür.
metrics[]	string Yanıta eklenmesi gereken metrikler. Herhangi bir değer belirtilmezse bulunan tüm metrikler döndürülür. İzin verilen değerler: ["cumulative_layout_shift", "first_contentful_paint", "first_input_delay", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]
Birleştirme alanı url_pattern. url_pattern, kayıt araması için ana tanımlayıcıdır. Aşağıdakilerden yalnızca biri olabilir:
origin	string url_pattern "kaynak", bir web sitesinin kaynağı olan URL kalıbını belirtir. Örnekler: "https://example.com", "https://cloud.google.com"
url	string url_pattern url, rastgele bir URL olan bir URL kalıbını belirtir. Örnekler: "https://example.com/, https://cloud.google.com/why-google-cloud/"

Örneğin, Chrome geliştirici dokümanları ana sayfası için masaüstü en büyük zengin içerikli boyama değerlerini istemek için:

{
  "url": "https://developer.chrome.com/docs/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

Yanıt gövdesi

Başarılı istekler, aşağıdaki yapıda bir record nesnesi ve urlNormalizationDetails ile yanıtlar döndürür:

{
  "record": {
    "key": {
      object (Key)
    },
    "metrics": [
      string: {
        object (Metric)
      }
    ]
  },
  "urlNormalizationDetails": {
    object (UrlNormalization)
  }
}

Örneğin, önceki istekte istek gövdesinin yanıtı şöyle olabilir:

{
  "record": {
    "key": {
      "formFactor": "DESKTOP",
      "url": "https://developer.chrome.com/docs/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.9815
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.0108
          },
          {
            "start": 4000,
            "density": 0.0077
          }
        ],
        "percentiles": {
          "p75": 651
        }
      }
    },
    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }
  }
}

Anahtar

Key, bu kaydı benzersiz olarak tanımlayan tüm boyutları tanımlar.

{
  "effectiveConnectionType": string,
  "formFactor": enum (FormFactor),

  // Union field url_pattern can be only one of the following:
  "origin": string,
  "url": string
  // End of list of possible types for union field url_pattern.
}

Alanlar
formFactor	enum (FormFactor) Form faktörü, tüm kullanıcıların bu kayıt için siteye erişmek üzere kullandığı cihaz sınıfıdır. Form faktörü belirtilmemişse tüm form faktörlerinden toplanan veriler döndürülür.
effectiveConnectionType	string Etkin bağlantı türü, tüm kullanıcıların bu kayıt için yaşadığı genel bağlantı sınıfıdır. Bu alanda, şu adreste belirtildiği gibi ["offline", "slow-2G", "2G", "3G", "4G"] değerleri kullanılır: https://wicg.github.io/netinfo/#effective-connection-types Etkili bağlantı türü belirtilmemişse tüm etkin bağlantı türleri üzerinden birleştirilmiş veriler döndürülür.
Birleştirme alanı url_pattern. URL kalıbı, kaydın geçerli olduğu URL'dir. url_pattern şunlardan yalnızca biri olabilir:
origin	string origin, bu kaydın ait olduğu kaynağı belirtir. Not: Bir origin belirtilirken, tüm sayfalardaki bu kaynak altındaki yüklemelere ilişkin veriler, kaynak düzeyindeki kullanıcı deneyimi verileri olarak toplanır.
url	string url, bu kaydın ait olduğu belirli bir URL'yi belirtir. Not: url belirtirken yalnızca söz konusu URL'nin verileri toplanır.

Metrikler

metric, ilk zengin içerikli boyama gibi tek bir web performansı metriği için toplu kullanıcı deneyimi verileri grubudur. Gerçek Chrome kullanımının bir dizi bins halinde özet histogramını, belirli yüzdelik dilim verilerini (p75 gibi) veya etiketli kesirleri içerebilir.

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

veya

{
  "fractions": {
    object (Fractions)
  }
}

Alanlar
histogram[]	object (Bin) Bir metrikle ilgili kullanıcı deneyimleri histogramı. Histogramda en az bir bölme olacak ve tüm bölmelerin yoğunlukları ~1'e eşit olacaktır.
percentiles	object (Percentiles) Metriğin yaygın faydalı yüzdelik dilimleri. Yüzdelik dilimlerin değer türü, Histogram bölmeleri için belirtilen değer türleriyle aynı olur.
fractions	object (Fractions) Bu nesne etiketli kesirler içeriyor. Bu kesirlerin toplamı ~1 ediyor. Kesirler, 4 ondalık basamak olacak şekilde yuvarlanır.

Bölme

bin, başlangıçtan sona kadar değişen veya herhangi bir bitiş noktasından pozitif sonsuza kadar herhangi bir bitiş belirtilmemişse, verilerin ayrı bir kısmıdır.

Bir bölmenin başlangıç ve bitiş değerleri, temsil ettiği metriğin değer türüne göre verilir. Örneğin, ilk zengin içerikli boyama milisaniye cinsinden ölçülür ve ints olarak gösterilir. Bu nedenle, metrik bölmelerinde başlangıç ve bitiş türleri için int32s kullanılır. Bununla birlikte, kümülatif düzen kayması birimsiz ondalık sayılarla ölçülür ve dize olarak kodlanmış ondalık sayı şeklinde gösterilir. Bu nedenle, metrik bölmelerinde değer türü için dize kullanılır.

{
  "start": value,
  "end": value,
  "density": number
}

Alanlar
start	(integer | string) Başlangıç, veri bölmesinin başlangıcıdır.
end	(integer | string) Bitiş, veri bölmesinin sonudur. Bitiş doldurulmazsa, bölmenin sonu yoktur ve başlangıçtan +inf tarihine kadar geçerlidir.
density	number Belirli bir metrik için bu bölmenin değerini gören kullanıcıların oranı. Yoğunluklar 4 ondalık basamak olacak şekilde yuvarlanır.

Yüzdelik dilimler

Percentiles, belirli bir istatistiksel yüzdelik dilimde bir metriğin sentetik değerlerini içerir. Bunlar, kullanıcıların toplam kullanıcı sayısına göre belirli bir yüzdesinin deneyimlediği bir metriğin değerini tahmin etmek için kullanılır.

{
  "P75": value
}

Alanlar
p75	(integer | string) Sayfa yüklemelerinin% 75'inde ilgili metrik, bu değerde veya bu değerden düşük ile karşılaşıldı.

Kesirler

Fractions, toplamı 1'e eşit olan etiketli kesirler içeriyor. Her etiket bir sayfa yüklemesini bir şekilde tanımlar. Dolayısıyla bu şekilde temsil edilen metrikler, sayısal değerler yerine farklı değerler üretmek olarak düşünülebilir. Kesirler ise belirli bir farklı değerin ne sıklıkta ölçüldüğünü ifade eder.

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

Histogram kutularındaki yoğunluk değerlerine benzer şekilde her fraction sayıdır 0.0 <= value <= 1.0 ve toplamları ~1,0'a eşittir.

UrlNormalization

Başarılı arama olasılığını artırmak amacıyla bir URL'yi normalleştirmek için gerçekleştirilen normalleştirme işlemlerini temsil eden nesne. Bunlar, sağlanan url_pattern aranırken başarısız olduğu bilinen, otomatik olarak yapılan basit değişikliklerdir. Aşağıdaki yönlendirmeler gibi karmaşık işlemler işlenmez.

{
  "originalUrl": string,
  "normalizedUrl": string
}

Alanlar
originalUrl	string Herhangi bir normalleştirme işleminden önce istenen orijinal URL.
normalizedUrl	string Tüm normalleştirme işlemlerinden sonraki URL. Bu, makul bir şekilde bulunabilecek geçerli bir kullanıcı deneyimi URL'sidir.

Hız sınırları

CrUX API, her Google Cloud projesi için dakikada 150 sorguyla sınırlıdır. Bu sorgu ücretsiz olarak sunulur. Bu sınırı ve mevcut kullanımınızı Google Cloud Console'dan görebilirsiniz. Bu büyük kota, kullanım alanlarının büyük çoğunluğu için yeterli olacaktır ve artırılmış bir kota için ödeme yapmak mümkün değildir.