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'nin kullanılabilmesi için Chrome UX Report API
kullanımı için bir Google Cloud API anahtarı sağlanması gerekir.
API anahtarı edinme ve kullanma
Anahtar alveya Kimlik Bilgileri sayfasında bir tane oluşturun.
Bir API anahtarınız olduktan sonra, uygulamanız sorgu parametresini ekleyebilir
Tüm istek URL'lerine key=yourAPIKey
.
API anahtarı, URL'lere yerleştirmek için güvenlidir; herhangi bir kodlama yapmanız gerekmez.
Örnek sorgular bölümüne bakın.
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, her bir reklam grubuna düşen sayfa yüklemelerinin yüzdelerini zaman aralığı ekleyebilirsiniz.
Örnek bir metrik için üç 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 ölçüldüğünü göstermektedir. 0 ms. ile 1.000 ms. arasında olmalıdır. Metriğin birimleri bu histogramda yer almaz Bu örnekte, milisaniye cinsinden kabul edeceğiz.
Ayrıca, sayfa yüklemelerinin% 49,91'inde 1.000 ms ile 3.000 ms. arasında bir metrik değeri görüldü. Bu değer %11,92'dir 3.000 ms'den yüksek bir değer gördüm.
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 gruplanmış verileri değil, mevcut veri kümesinin tamamını temel alır O yüzden bu değerlerin, son binli histogram.
{
"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 istekteformFactor
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; her gün en iyi gayrete dayalı olarak çalıştırılır.
Ş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 |
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 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 |
Form faktörü, kayıt verilerinin ait olduğu cihaz sınıfını belirten bir sorgu boyutudur. Bu alanda 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[] |
Yanıta eklenmesi gereken metrikler. Herhangi bir değer belirtilmezse bulunan tüm metrikler döndürülür. İzin verilen değerler: |
Birleştirme alanı url_ . url_pattern , kayıt araması için ana tanımlayıcıdır. Aşağıdakilerden yalnızca biri olabilir: |
|
origin |
Örnekler: |
url |
Örnekler: |
Ö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 |
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 |
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_ . URL kalıbı, kaydın geçerli olduğu URL'dir. url_ şunlardan yalnızca biri olabilir: |
|
origin |
Not: Bir |
url |
Not: |
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
, belirli yüzdelik dilim verileri olarak özet histogramını içerebilir
(p75 gibi) veya etiketli kesirler içeriyor olabilir.
{
"histogram": [
{
object (Bin)
}
],
"percentiles": {
object (Percentiles)
}
}
veya
{
"fractions": {
object (Fractions)
}
}
Alanlar | |
---|---|
histogram[] |
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 |
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 |
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ş sağlanmamışsa, 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 |
Başlangıç, veri bölmesinin başlangıcıdır. |
end |
Bitiş, veri bölmesinin sonudur. Bitiş doldurulmazsa, bölmenin sonu yoktur ve başlangıçtan +inf tarihine kadar geçerlidir. |
density |
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 |
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
bir şekilde temsil edilir. Dolayısıyla, bu şekilde temsil edilen metrikler,
yerine farklı değerler üretir ve kesirler bunu ifade eder
Belirli bir farklı değerin ne sıklıkta ölçüldüğünü gösterir.
{
"label_1": fraction,
"label_2": fraction,
...
"label_n": fraction
}
Histogram kutularındaki yoğunluk değerlerine benzer şekilde, her fraction
bir sayıdır
0.0 <= value <= 1.0
ve bunların toplamı yaklaşık 1, 0.
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 |
Herhangi bir normalleştirme işleminden önce istenen orijinal URL. |
normalizedUrl |
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.