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 istekteformFactor
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 |
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 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 |
Form faktörü, kayıt verilerinin ait olması gereken cihaz sınıfını belirten bir sorgu boyutudur. Bu alan 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[] |
Yanıta dahil edilmesi gereken metrikler. Herhangi bir metrik belirtilmezse bulunan tüm metrikler döndürülür. İzin verilen değerler: |
Birleştirme alanı url_ . url_pattern , kayıt arama için ana tanımlayıcıdır. Aşağıdakilerden yalnızca biri olabilir: |
|
origin |
Örnekler: |
url |
Örnekler: |
Ö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 |
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 |
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_ . URL kalıbı, kaydın uygulandığı URL'dir. url_ şunlardan yalnızca biri olabilir: |
|
origin |
Not: |
url |
Not: |
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[] |
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 |
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 |
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 |
Başlangıç, veri bölmesinin başıdır. |
end |
Bitiş, veri bölmesinin sonudur. Bitiş alanı doldurulmazsa bölmenin sonu yoktur ve başlangıcından +sona kadar geçerli olur. |
density |
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 |
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 |
Herhangi bir normalleştirme işleminden önce istenen orijinal URL. |
normalizedUrl |
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.