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, belirli bir URI için kullanıcı deneyimi metriklerinin sorgulanmasına olanak tanır (ör. "https://example.com kaynağı için metrikleri al").
CrUX API anahtarı
CrUX API'yi kullanmak için Chrome UX Report API kullanımı için sağlanmış bir Google Cloud API anahtarı gerekir.
API anahtarı edinme ve kullanma
Anahtar almaveya Kimlik Bilgileri sayfasında bir tane oluşturun.
API anahtarınız olduktan sonra uygulamanız, key=yourAPIKey sorgu parametresini tüm istek URL'lerine ekleyebilir.
API anahtarı, URL'lere yerleştirmek için güvenlidir; herhangi bir kodlama yapmanız gerekmez.
Örnek sorgular bölümünü inceleyin.
Veri modeli
Bu bölümde, istek ve yanıtlardaki verilerin yapısı ayrıntılı olarak açıklanmaktadır.
Kaydet
Bir sayfa veya siteyle ilgili ayrı bir bilgi parçası. Bir kayıtta, bir tanımlayıcıya ve belirli bir boyut kombinasyonuna özgü veriler bulunabilir. Bir kayıt, bir veya daha fazla metrikle ilgili veriler içerebilir.
Tanımlayıcılar
Tanımlayıcılar, hangi kayıtların aranacağını belirtir. CrUX'te bu tanımlayıcılar web sayfaları ve web siteleridir.
Köken
Tanımlayıcı bir kaynak olduğunda, bu kaynaktaki tüm sayfalar için mevcut olan tüm veriler bir araya getirilir. Örneğin, http://www.example.com kaynağında bu site haritasında belirtilen sayfalar olduğunu varsayalım:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Bu, Chrome UX Report'u kaynak http://www.example.com olarak ayarlanmış şekilde sorgularken http://www.example.com/, http://www.example.com/foo.html ve http://www.example.com/bar.html ile ilgili verilerin döndürüleceği ve birleştirileceği anlamına gelir. Çünkü bunların tümü, söz konusu kaynak kapsamındaki sayfalardır.
URL'ler
Tanımlayıcı bir URL olduğunda yalnızca söz konusu URL'ye ait veriler döndürülür. http://www.example.com kaynak site haritasına tekrar bakarsak:
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 ilgili sayfanın verileri 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 bilgiler içerdiğini gösterir. Her boyutun belirli sayıda değeri olur ve bu boyutun belirtilmemesi, boyutun tüm değerler üzerinden toplandığı anlamına gelir. Örneğin, form faktörü belirtilmemesi, kaydın herhangi bir form faktöründe gerçekleşen yüklemelerle ilgili bilgiler 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ılan genel bir cihaz sınıfıdır.
Metrik
Metrikleri histogramlar, yüzdelikler ve kesirler halinde istatistiksel toplamlar 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 olarak kabul edilmediğini ve dize içinde 2 ondalık basamağa kadar raporlandığını unutmayın).
Histogram
Metrikler histogramda gösterildiğinde, ilgili metrik için belirli aralıklara giren sayfa yükleme yüzdelerini gösteririz.
Örnek bir metrik için üç bölmeli histogram şu şekilde 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österir. Metriğin birimleri bu histogramda yer almıyor. Bu durumda milisaniye olarak kabul edeceğiz.
Ayrıca, sayfa yüklemelerinin %49,91'inde 1.000 ms ile 3.000 ms arasında bir metrik değeri, %11,92'sinde ise 3.000 ms'den büyük bir değer görüldü.
Yüzdelikler
Metrikler, ek analizler için yararlı olabilecek yüzdelik dilimler de içerebilir. Belirli metrik değerlerini, ilgili metrik için belirtilen yüzdelik dilimde raporlarız. Bu değerler, nihai gruplandırılmış verileri değil, mevcut verilerin tamamını temel alır. Bu nedenle, nihai gruplandırılmış histogramı temel alan bir enterpolasyonlu yüzdelik dilimle eşleşmeleri gerekmez.
{
"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üzdelerini gösterir. Bu durumda, metrik değerleri bu etiketlerdir.
Örneğin, form_factors metriği, söz konusu 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 durumda, sayfa yüklemelerinin %3,77'si masaüstünde, %2,88'i tablette ve %93,35'i telefonda ölçülerek toplamda %100'e ulaşılmıştır.
Metrik değer türleri
| CrUX API Metrik Adı | Veri Türü | Metrik Birimler | İstatistiksel Toplamalar | Belgeler |
|---|---|---|---|---|
cumulative_layout_shift |
Dize olarak kodlanmış 2 ondalık basamaklı double | birimsiz | üç bölmeli histogram, p75 ile yüzdelik dilimler | CLS |
interaction_to_next_paint |
int | milisaniye | üç bölmeli histogram, p75 ile yüzdelik dilimler | INP |
largest_contentful_paint |
int | milisaniye | üç bölmeli histogram, p75 ile yüzdelik dilimler | LCP |
experimental_cumulative_layout_shift_with_softnavs |
Dize olarak kodlanmış 2 ondalık basamaklı double | birimsiz | üç bölmeli histogram, p75 ile yüzdelik dilimler | Blog |
experimental_interaction_to_next_paint_with_softnavs |
int | milisaniye | üç bölmeli histogram, p75 ile yüzdelik dilimler | Blog |
experimental_largest_contentful_paint_with_softnavs |
int | milisaniye | üç bölmeli histogram, p75 ile yüzdelik dilimler | Blog |
first_contentful_paint |
int | milisaniye | üç bölmeli histogram, p75 ile yüzdelik dilimler | FCP |
experimental_first_contentful_paint_with_softnavs |
int | milisaniye | üç bölmeli histogram, p75 ile yüzdelik dilimler | Blog |
experimental_time_to_first_byte |
int | milisaniye | üç bölmeli histogram, p75 ile yüzdelik dilimler | TTFB |
form_factors |
4 ondalık basamaklı ondalıklı sayı | yüzde | form faktöründen kesre eşleme | Form Faktörleri |
navigation_types |
4 ondalık basamaklı ondalıklı sayı | yüzde | gezinme türünden kesre eşleme | Gezinme Türleri |
experimental_navigation_types_with_softnavs |
4 ondalık basamaklı ondalıklı sayı | yüzde | gezinme türünden kesre eşleme | Blog |
round_trip_time |
int | milisaniye | üç bölmeli histogram, p75 ile yüzdelik dilimler | RTT metriği |
largest_contentful_paint_resource_type |
4 ondalık basamaklı ondalıklı sayı | yüzde | gezinme türünden kesre eşleme | LCP kaynak türleri |
largest_contentful_paint_image_time_to_first_byte |
int | milisaniye | p75 ile yüzdelik dilimler | LCP alt bölümleri |
largest_contentful_paint_image_resource_load_delay |
int | milisaniye | p75 ile yüzdelik dilimler | LCP alt bölümleri |
largest_contentful_paint_image_resource_load_duration |
int | milisaniye | p75 ile yüzdelik dilimler | LCP alt bölümleri |
largest_contentful_paint_image_element_render_delay |
int | milisaniye | p75 ile yüzdelik dilimler | LCP alt bölümleri |
experimental_ad_count |
2 ondalık basamaklı ondalıklı sayı | birimsiz | Yalnızca 75. yüzdelik dilim | Reklam Sayısı |
experimental_ad_density |
2 ondalık basamaklı ondalıklı sayı | birimsiz | Yalnızca 75. yüzdelik dilim | Reklam yoğunluğu |
experimental_ad_cpu |
int | milisaniye | Yalnızca 75. yüzdelik dilim | Reklam Ağırlığı: CPU |
experimental_ad_kilobytes |
int | KB | Yalnızca 75. yüzdelik dilim | Reklam Ağırlığı: Ağ |
BigQuery metrik adı eşleme
| CrUX API Metrik Adı | BigQuery metrik adı |
|---|---|
cumulative_layout_shift |
layout_instability.cumulative_layout_shift |
first_contentful_paint |
first_contentful_paint |
interaction_to_next_paint |
interaction_to_next_paint |
largest_contentful_paint |
largest_contentful_paint |
experimental_time_to_first_byte |
experimental.time_to_first_byte |
experimental_cumulative_layout_shift_with_softnavs |
experimental.cumulative_layout_shift_with_softnavs |
experimental_first_contentful_paint_with_softnavs |
n/a |
experimental_interaction_to_next_paint_with_softnavs |
experimental.interaction_to_next_paint_with_softnavs |
experimental_largest_contentful_paint_with_softnavs |
experimental.largest_contentful_paint_with_softnavs |
navigation_types |
navigation_types |
experimental_navigation_types_with_softnavs |
n/a |
form_factors |
Yok |
round_trip_time |
round_trip_time |
largest_contentful_paint_resource_type |
Yok |
largest_contentful_paint_image_time_to_first_byte |
Yok |
largest_contentful_paint_image_resource_load_delay |
Yok |
largest_contentful_paint_image_resource_load_duration |
Yok |
largest_contentful_paint_image_element_render_delay |
Yok |
experimental_ad_count |
n/a |
experimental_ad_density |
n/a |
experimental_ad_cpu |
n/a |
experimental_ad_kilobytes |
n/a |
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ı içeren bir collectionPeriod nesnesi barındırır. Örneğin:
"collectionPeriod": {
"firstDate": {
"year": 2022,
"month": 9,
"day": 12
},
"lastDate": {
"year": 2022,
"month": 10,
"day": 9
}
}
Bu sayede veriler daha iyi anlaşılır ve verilerin o gün için güncellenip güncellenmediği veya dünkü verilerin aynısını döndürüp döndürmediği anlaşılır.
Toplama dönemi PageSpeed Insights'ta da mevcuttur:
Ayrıca, veriler 28 günün tamamını kapsamasa bile (örneğin, bir sayfa 28 günden daha kısa bir süre önce yayınlandıysa) collectionPeriod her zaman 28 günü gösterir. collectionPeriod, CrUX verilerinin toplandığı dönemdir. Bu, verilerin temsil ettiği dönem olmayabilir.
Örnek sorgular
Sorgular, POST gövdesinde JSON nesnesi olarak sorgu verileriyle birlikte https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" adresine 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 komut curl üzerinden aşağıdaki komut satırı ile çağrılabilir (API_KEY yerine anahtarınızı yazın):
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 verilere, sorguda origin yerine url mülkü iletilerek API aracılığıyla erişilebilir:
{
"url": "https://example.com/page",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
metrics özelliği ayarlanmazsa mevcut tüm metrikler döndürülür:
cumulative_layout_shiftfirst_contentful_paintinteraction_to_next_paintlargest_contentful_paintexperimental_cumulative_layout_shift_with_softnavsexperimental_first_contentful_paint_with_softnavsexperimental_interaction_to_next_paint_with_softnavsexperimental_largest_contentful_paint_with_softnavsexperimental_navigation_types_with_softnavsexperimental_time_to_first_bytelargest_contentful_paint_resource_typelargest_contentful_paint_image_time_to_first_bytelargest_contentful_paint_image_resource_load_delaylargest_contentful_paint_image_resource_load_durationlargest_contentful_paint_image_element_render_delaynavigation_typesround_trip_timeform_factors(yalnızca istekteformFactorbelirtilmemişse raporlanır)experimental_ad_count(yalnızca reklam metriklerine dahil edilen sayfalar için raporlanır)experimental_ad_density(yalnızca reklam metriklerine dahil edilen sayfalar için raporlanır)experimental_ad_cpu(yalnızca reklam metriklerine dahil edilen sayfalar için raporlanır)experimental_ad_kilobytes(yalnızca reklam metriklerine dahil edilen sayfalar için raporlanır)
formFactor değeri sağlanmazsa değerler tüm form faktörleri genelinde toplanır.
Daha fazla örnek sorgu için Chrome UX Report API'yi kullanma başlıklı makaleyi inceleyin.
Veri ardışık düzeni
CrUX veri kümesi, API kullanılarak erişilebilir hale gelmeden önce verileri birleştirmek, toplamak ve filtrelemek için bir ardışık düzenden geçirilir.
Hareketli ortalama
Chrome UX Report'taki veriler, toplu metriklerin 28 günlük hareketli ortalamasıdır. Bu, Chrome UX Report'ta herhangi bir zamanda sunulan verilerin aslında son 28 güne ait verilerin bir araya getirilmiş hali olduğu anlamına gelir.
Bu, BigQuery'deki CrUX veri kümesinin aylık raporları toplama şekline 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. Güncelleme işlemi her gün, yalnızca olabildiğince gerçekleştirilir.
Şema
CrUX API için POST HTTP isteklerini kabul eden tek bir uç nokta vardır. API, istenen kaynak veya sayfa ile 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 metni
İstek içeriği aşağıdaki yapıyla birlikte verileri içermelidir:
{
"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 | |
|---|---|
formFactor |
Form faktörü, kaydın verilerinin ait olması gereken cihaz sınıfını belirten bir sorgu boyutudur. Bu alanda Not: Herhangi bir form faktörü belirtilmezse tüm form faktörleri genelinde birleştirilmiş verileri içeren özel bir kayıt döndürülür. |
metrics[] |
Yanıta dahil edilmesi gereken metrikler. Hiçbir metrik belirtilmezse bulunan tüm metrikler döndürülür. İzin verilen değerler: |
url_ birleşik alanı. url_pattern, kayıt aramada kullanılan 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ının masaüstü Largest Contentful Paint değerlerini istemek için:
{
"url": "https://developer.chrome.com/docs/",
"formFactor": "DESKTOP",
"metrics": [
"largest_contentful_paint"
]
}
Yanıt metni
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 şu şekilde 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.
{
"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ü belirtilmezse tüm form faktörleri üzerinden birleştirilmiş veriler döndürülür. |
url_ birleşik alanı. URL kalıbı, kaydın geçerli olduğu URL'dir. url_ aşağıdakilerden yalnızca biri olabilir: |
|
origin |
Not: Bir |
url |
Not: Bir |
Metrikler
metric, tek bir web performansı metriği (ör. ilk zengin içerikli boyama) için toplu kullanıcı deneyimi verileri kümesidir.
Gerçek dünyadaki Chrome kullanımının özet histogramını bir dizi bins, belirli yüzdelik dilim verileri (ör. p75) olarak içerebilir veya etiketli kesirler içerebilir.
{
"histogram": [
{
object (Bin)
}
],
"percentiles": {
object (Percentiles)
}
}
veya
{
"fractions": {
object (Fractions)
}
}
| Alanlar | |
|---|---|
histogram[] |
Bir metriğe ait kullanıcı deneyimlerinin histogramı. Histogramda en az bir aralık bulunur ve tüm aralıkların yoğunluklarının toplamı yaklaşık 1'dir. |
percentiles |
Metriğin yaygın olarak kullanılan faydalı yüzdelik dilimleri. Yüzdelik dilimlerin değer türü, histogram bölmeleri için verilen değer türleriyle aynı olur. |
fractions |
Bu nesne, toplamı yaklaşık 1 olan etiketli kesirler içerir. Kesirler 4 ondalık basamağa yuvarlanır. |
Bölme
bin, başlangıçtan bitişe kadar veya bitiş belirtilmemişse başlangıçtan pozitif sonsuza kadar uzanan ayrı bir veri bölümüdür.
Bir aralığın 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 tam sayı olarak gösterilir. Bu nedenle, metrik grupları başlangıç ve bitiş türleri için int32'leri kullanır. Ancak kümülatif düzen kayması, birimsiz ondalık sayılarla ölçülür ve dize olarak kodlanmış bir ondalık sayı olarak gösterilir. Bu nedenle, metrik grupları değer türü için dizeleri kullanır.
{
"start": value,
"end": value,
"density": number
}
| Alanlar | |
|---|---|
start |
Başlangıç, veri grubunun başlangıcıdır. |
end |
Bitiş, veri grubunun sonudur. Bitiş doldurulmazsa aralığın bitişi olmaz ve başlangıçtan +inf'ye kadar geçerli olur. |
density |
Belirli bir metrik için bu aralığın değerini deneyimleyen kullanıcıların oranı. Yoğunluklar 4 ondalık basamağa yuvarlanır. |
Yüzdelikler
Percentiles, belirli bir istatistiksel yüzdelik dilimdeki bir metriğin yapay değerlerini içerir. Bunlar, toplam kullanıcı sayısının belirli bir yüzdesi tarafından deneyimlenen bir metriğin değerini tahmin etmek için kullanılır.
{
"P75": value
}
| Alanlar | |
|---|---|
p75 |
Sayfa yüklemelerinin %75'inde, belirtilen metrik bu değerde veya bu değerin altında gerçekleşti. |
Kesirler
Fractions, toplamı yaklaşık 1 olan etiketli kesirler içeriyor. Her etiket, sayfa yüklemeyi bir şekilde açıklar. Bu nedenle, bu şekilde temsil edilen metriklerin sayısal değerler yerine farklı değerler ürettiği düşünülebilir ve kesirler, belirli bir farklı değerin ne sıklıkta ölçüldüğünü ifade eder.
{
"label_1": fraction,
"label_2": fraction,
...
"label_n": fraction
}
Histogram bölmelerindeki yoğunluk değerleri gibi, her bir fraction bir sayıdır 0.0 <= value <= 1.0 ve toplamları yaklaşık 1,0'dır.
UrlNormalization
Başarılı bir arama ş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 başarısız olacağı bilindiğinde yapılan temel, otomatik değişikliklerdir. Yönlendirmeleri takip etme gibi karmaşık işlemler gerçekleştirilmez.
{
"originalUrl": string,
"normalizedUrl": string
}
| Alanlar | |
|---|---|
originalUrl |
Herhangi bir normalleştirme işleminden önceki orijinal istek URL'si. |
normalizedUrl |
Normalleştirme işlemlerinden sonraki URL. Bu, makul bir şekilde aranabilecek geçerli bir kullanıcı deneyimi URL'sidir. |
Hız sınırları
CrUX API, Google Cloud projesi başına dakikada 150 sorgu ile sınırlıdır ve ücretsiz olarak sunulur. 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 ücret karşılığında kotayı artırmak mümkün değildir.