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 alma" gibi belirli bir URI için kullanıcı deneyimi metriklerinin sorgulanmasını sağlar.

CrUX API Anahtarı

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

Bir API anahtarınız olduktan sonra, uygulamanız key=[YOUR_API_KEY] sorgu parametresini tüm istek URL'lerine ekleyebilir. Örnek sorgulara 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ı bir şekilde açıklanmaktadır.

Kaydet

Bir sayfa veya site hakkında ayrı bir bilgi parçası. Bir kayıtta, bir tanımlayıcı ve belirli bir boyut kombinasyonu için özel veriler bulunabilir. Bir kayıt, bir veya daha fazla metriğe ait veri 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 bir araya toplanır. Örneğin, http://www.example.com kaynağının şu site haritasında belirtilen sayfalara sahip olduğunu varsayalım:

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

Bu, kaynağı http://www.example.com olarak ayarlanmış Chrome Kullanıcı Deneyimi Raporu'nu sorgularken, http://www.example.com/, http://www.example.com/foo.html ve http://www.example.com/bar.html verilerinin, bu kaynağın altındaki tüm sayfalar olduğundan toplu halde döndürüleceği anlamına gelir.

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 bakılıyor:

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ğerine sahip URL olarak ayarlanırsa yalnızca bu sayfaya ilişkin 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 dolaylı olarak bu boyutun belirtilmemesi, boyutun tüm değerlerden toplandığı anlamına gelir. Örneğin, "form faktörü yok" ifadesinin belirtilmesi, kaydın herhangi bir form faktöründe gerçekleştirilen yüklemelerle ilgili bilgi içerdiğini belirtir.

Form Faktörü

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

Etkili Bağlantı Türü

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

Metrik

Metrikleri histogramlar, yüzdelik dilimler ve kesirler halinde istatistiksel toplamalar olarak raporlarız.

Kayan nokta değerleri 4 ondalık basamağa yuvarlanır (cumulative_layout_shift metriklerinin dize olarak kodlanmış çiftler olduğunu, bu nedenle kayan nokta kabul edilmediğini ve dize içinde 2 ondalık basamağa raporlandığını unutmayın).

Histogram

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

Basit bir üç bin histogram örnek bir metrik 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'i için örnek metriğin 0 ms ile 1.000 ms arasında ölçüldüğünü gösterir. Metriğin birimleri bu histogramda yer almaz. Bu örnekte, milisaniye olduğu varsayılır.

Buna ek olarak, sayfa yüklemelerinin% 49,91'inde 1.000 ms. ile 3.000 ms. arasında ve %11,92'sinde 3.000 ms.den büyük bir metrik değeri görüldü.

Yüzdelik dilimler

Metrikler, ek analiz için yararlı olabilecek yüzdelik dilimler de içerebilir. Belirli metrik değerlerini, söz konusu metrik için verilen yüzdelik dilimde raporlarız. Bunlar, birleştirilmiş nihai verilere değil, kullanılabilir verilerin tamamına dayanır. Bu yüzden, nihai birleştirilmiş histograma dayanan ara değerlenmiş bir yüzdelik dilim ile eşleşmek zorunda değildirler.

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

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

Kesirler

Kesirler, belirli bir şekilde etiketlenebilecek sayfa yüklemelerinin yüzdesini belirtir. Bu durumda, metrik değerleri bu etiketlerdir.

Örneğin, form_factors metriği, belirli bir 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 (toplamın% 100'ü).

Metrik değer türleri

CrUX API Metrik Adı	Veri Türü	Metrik Birimler	İstatistiksel Toplamalar	Belgeler
cumulative_layout_shift	Dize olarak çift kodlanmış 2 ondalık basamak	birimsiz	üç bölmeli histogram, yüzdelik dilim ve p75	cls
first_contentful_paint	int	milisaniye	üç bölmeli histogram, yüzdelik dilim ve p75	fcp
first_input_delay (kullanımdan kaldırıldı)	int	milisaniye	üç bölmeli histogram, yüzdelik dilim ve p75	araştırma
interaction_to_next_paint	int	milisaniye	üç bölmeli histogram, yüzdelik dilim ve p75	inp
largest_contentful_paint	int	milisaniye	üç bölmeli histogram, yüzdelik dilim ve p75	lcp
experimental_time_to_first_byte	int	milisaniye	üç bölmeli histogram, yüzdelik dilim ve p75	ttfb
form_factors	4 ondalık basamak çift	yüzde	form faktöründen kesere eşleme	form faktörleri
navigation_types	4 ondalık basamak çift	yüzde	gezinme türünden kesere eşleme	gezinme türleri

BigQuery metrik adı eşlemesi

CrUX API Metrik Adı	BigQuery Metrik 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

Toplama dönemi

Ekim 2022'den itibaren CrUX API'de, toplama aralığının başlangıç ve bitiş tarihlerini temsil eden firstDate ve endDate alanlarının bulunduğu bir collectionPeriod nesnesi bulunuyor. Örneğin:

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

Bu, verilerin daha iyi anlaşılmasını ve verilerin ilgili gün için güncellenip güncellenmediğini veya dündekiyle aynı verileri mi döndürdüğünü daha iyi anlamanızı sağlar.

CrUX API'nin, ilgili gün için tamamlanan verileri beklediğinden bugünün tarihinden yaklaşık iki gün geride olduğunu ve API'de kullanıma sunulmadan önce bir miktar işleme süresinin geçtiğini unutmayın. Kullanılan saat dilimi, Pasifik Standart Saati'dir (PST). Yaz saati uygulaması için herhangi bir değişiklik yoktur.

Örnek sorgular

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

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

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

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üzeyi veriler, sorguya origin yerine 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 (kullanımdan kaldırıldı)
• interaction_to_next_paint
• largest_contentful_paint
• experimental_time_to_first_byte
• navigation_types
• form_factors (yalnızca istekte formFactor belirtilmemişse raporlanır)

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

Diğer örnek sorgular için Chrome UX Report API'yi Kullanma bölümüne bakın.

Veri ardışık düzeni

CrUX veri kümesi, API kullanılarak kullanılabilir hale gelmeden önce verileri birleştirmek, toplamak ve filtrelemek için bir ardışık düzen üzerinden işlenir.

Hareketli ortalama

Chrome Kullanıcı Deneyimi Raporu'ndaki veriler, birleştirilmiş metriklerin 28 günlük hareketli ortalamasıdır. Bu, herhangi bir zamanda Chrome Kullanıcı Deneyimi Raporu'nda sunulan verilerin aslında son 28 güne ait birleştirilmiş veriler olduğu anlamına gelir.

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 süreleri için hizmet düzeyi sözleşmesi yoktur; her gün en iyi çaba esasına göre yürütülür.

Şema

CrUX API için POST HTTP isteklerini kabul eden tek bir uç nokta vardır. 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

İsteğin gövdesi, aşağıdaki yapıya sahip veriler 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 Etkili bağlantı türü, kayıt verilerinin ait olması gereken etkili ağ sınıfını belirten bir sorgu boyutudur. Bu alan, Network Information API spesifikasyonunda belirtilen ["offline", "slow-2G", "2G", "3G", "4G"] değerlerini kullanır Not: Etkili bir bağlantı türü belirtilmezse tüm etkili 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 olması gereken cihaz sınıfını belirten bir sorgu boyutudur. Bu alan DESKTOP, PHONE veya TABLET değerlerini kullanır. Not: Form faktörü belirtilmezse tüm form faktörleri üzerinden birleştirilmiş verileri içeren özel bir kayıt döndürülür.
metrics[]	string Yanıta dahil edilmesi gereken metrikler. Herhangi bir metrik 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 arama 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ı ifade eder. Örnekler: "https://example.com", "https://cloud.google.com"
url	string url_pattern url, herhangi bir rastgele URL olan bir URL kalıbını belirtir. Örnekler: "https://example.com/, https://cloud.google.com/why-google-cloud/"

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

{
  "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 içeren yanıtlar döndürür:

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

Örneğin, önceki istekteki istek gövdesine verilen 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örleri üzerinden birleştirilmiş veriler döndürülür.
effectiveConnectionType	string Etkili bağlantı türü, tüm kullanıcıların bu kayıt için deneyimlediği genel bağlantı sınıfıdır. Bu alanda, https://wicg.github.io/netinfo/#effective-connection-types adresinde belirtildiği gibi, ["offline", "slow-2G", "2G", "3G", "4G"] değerleri kullanılır Etkin bağlantı türü belirtilmezse tüm etkili bağlantı türleri üzerinden birleştirilmiş veriler döndürülür.
Birleştirme alanı url_pattern. URL kalıbı, kaydın uygulandığı URL'dir. url_pattern şunlardan yalnızca biri olabilir:
origin	string origin bu kaydın ait olduğu kaynağı belirtir. Not: origin belirtilirken, tüm sayfalar üzerinden bu kaynak altındaki yükleme verileri kaynak düzeyindeki kullanıcı deneyimi verileri olarak birleştirilir.
url	string url, bu kaydın ait olduğu belirli bir URL'yi belirtir. Not: url belirtilirken yalnızca bu belirli URL için veriler toplanır.

Metrikler

metric, ilk zengin içerikli boyama gibi tek bir web performansı metriğine ait birleştirilmiş kullanıcı deneyimi verileri grubudur. Bir bins serisi olarak gerçek Chrome kullanımının özet histogramını, belirli yüzdelik verileri (p75 gibi) veya etiketli kesirler içerebilir.

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

veya

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

Alanlar
histogram[]	object (Bin) Bir metrik için kullanıcı deneyimlerinin histogramı. Histogramda en az bir bölme bulunur ve tüm bölmelerin yoğunluklarının toplamı yaklaşık 1 olur.
percentiles	object (Percentiles) Metriğin sık kullanılan kullanışlı yüzdelikleri. Yüzdelik dilimlere ilişkin değer türü, Histogram kutuları için verilen değer türleriyle aynı olacaktır.
fractions	object (Fractions) Bu nesne, toplamı yaklaşık 1 olan etiketli kesirler içeriyor. Kesirler, 4 ondalık basamağa yuvarlanır.

Bölme

bin, baştan sona yayılan veya başlangıcından pozitif sonsuza kadar hiçbir bitiş belirtilmemişse verilerin ayrı bir bölümüdür.

Bir bölmenin başlangıç ve bitiş değerleri, temsil ettiği metriğin değer türünde verilir. Örneğin, ilk zengin içerikli boyama, milisaniye cinsinden ölçülür ve ints olarak gösterilir. Bu nedenle, metrik kutuları başlangıç ve bitiş türleri için int32s'yi kullanır. Bununla birlikte, kümülatif düzen kayması, birimsiz ondalık sayılar halinde ölçülür ve dize olarak kodlanmış ondalık sayı biçiminde gösterilir. Bu nedenle, metrik kutuları kendi değer türü için dizeler kullanır.

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

Alanlar
start	(integer | string) Başlangıç, veri bölmesinin başıdır.
end	(integer | string) Bitiş, veri bölmesinin sonudur. Bitiş alanı doldurulmazsa bölmenin sonu yoktur ve başlangıcından +sona kadar geçerli olur.
density	number Belirli bir metrik için bu bölmenin değerini yaşayan kullanıcıların oranı. Yoğunluklar 4 ondalık basamağa yuvarlanır.

Yüzdelik dilimler

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

{
  "P75": value
}

Alanlar
p75	(integer | string) Sayfa yüklemelerinin% 75'inde, belirtilen metrik bu değerde veya bu değerden daha düşük düzeyde gerçekleşmiştir.

Kesirler

Fractions, toplamı yaklaşık 1 olan etiketli kesirler içeriyor. Her etiket bir sayfa yüklemesini bir şekilde tanımlar. Bu nedenle, bu şekilde temsil edilen metrikler, sayısal değerler yerine farklı değerler üretmek üzere düşünülebilir. Kesirler de 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 çok benzer şekilde, her fraction bir 0.0 <= value <= 1.0 sayıdır ve toplamı yaklaşık 1, 0'dır.

UrlNormalization

Aramanın başarılı olma şansını artırmak için URL'yi normalleştirmek üzere gerçekleştirilen normalleştirme işlemlerini temsil eden nesne. Bunlar, sağlanan url_pattern aranırken yapılan basit otomatik 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 Normalleştirme işlemlerinden sonraki URL. Bu, makul şekilde aranabilir olan geçerli bir kullanıcı deneyimi URL'sidir.

Hız sınırları

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