CrUX History API, altı aylık geçmiş gerçek kullanıcı deneyimi verilerine sayfa ve kaynak ayrıntı düzeyinde düşük gecikmeli erişim sunar.
Yaygın kullanım alanı
CrUX History API, belirli bir URI için geçmiş kullanıcı deneyimi metriklerinin sorgulanmasına olanak tanır. Örneğin, "https://example.com
kaynağıyla ilgili geçmiş kullanıcı deneyimi trendlerini öğrenin."
Değerlerin bir dizi içinde verilmesi ve anahtarların çoğul adlarla etiketlenmesi (örneğin, histogram
yerine histogramTimeseries
veya p75
yerine p75s
) hariç, History API, günlük CrUX API ile aynı yapıyı izler.
CrUX API Anahtarı
Günlük API'de olduğu gibi, CrUX History API'yi kullanmak için Chrome UX Report API
kullanımı için sağlanan bir Google Cloud API anahtarı gerekir. Günlük API ve geçmiş API'si için aynı anahtar kullanılabilir.
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 birleştirildiği 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.
CrUX History API yalnızca form faktörü boyutuna göre toplu olarak kullanılabilir. Bu; PHONE
, TABLET
ve DESKTOP
olarak ayrılmış genel bir cihaz sınıfıdır.
Metrik
Metrikleri, istatistiksel toplama zaman serileri (histogram, yüzdelik dilim, dilim) halinde raporlarız ve kesirleri de kullanabilirsiniz.
Histogramlar
Metrikler bir histogram dizisinde ifade edildiğinde, her zaman serisi girişi metriğin, tümüyle orantılı olarak bir aralığa denk düştüğü sayfa yüklemeleridir. Veri noktaları, API tarafından da döndürülen toplama dönemi tarihleri sırasına göre sunulur. İlk nokta en erken dönem, son nokta ise en son veri toplama dönemidir.
Örnek bir metrik için üç bin histogramı aşağıdaki gibi görünür:
{
"histogramTimeseries": [
{
"start": 0,
"end": 2500,
"densities": [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]
},
{
"start": 2500,
"end": 4000,
"densities": [0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527]
},
{
"start": 4000,
"densities": [0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285]
}
],
}
Bu veriler, geçmişteki ilk toplama döneminde sayfa yüklemelerinin% 91,90'ında 0 ms ile 2.500 ms arasında örnek metrik değerinin, ardından %92,03, %91,94... Metriğin birimleri bu histogramda yer almaz. Bu örnekte, milisaniye değerini kabul edeceğiz.
Ayrıca, geçmişteki ilk toplama döneminde sayfa yüklemelerinin% 5,21'inde örnek metrik değeri 2.500 ms. ile 4.000 ms. arasında olmuş, sayfa yüklemelerinin% 2,88'inde ise geçmişteki ilk toplama döneminde 4.000 ms.den yüksek bir değer gerçekleşmiştir.
Yüzdelik dilimler
Metrikler, ek analizler için yararlı olabilecek yüzdelik dilim zaman dizilerini de içerebilir.
Veri noktaları, API tarafından da döndürülen toplama dönemi tarihleri sırasına göre sunulur. İlk nokta en erken dönem, son nokta ise en son veri toplama dönemidir.
{
"percentilesTimeseries": {
"p75s": [1362, 1352, 1344, 1356, 1366, 1377]
},
}
Bu yüzdelik dilimler, söz konusu metrik için belirtilen yüzdelik dilimde belirli metrik değerlerini gösterebilir. Bunlar, nihai bağlı verilere değil, kullanılabilir verilerin tamamına dayanır ve bu nedenle, nihai binlenmiş histograma dayalı interpolasyon yüzdelik dilimle eşleşmezler.
Kesirler
Metrikler, etiketli kesirlerin zaman serisi olarak ifade edilebilir; her etiket belirli bir konumdaki bir sayfa yüklemesini sağlar. Veri noktaları, API tarafından da döndürülen toplama dönemi tarihleri sırasına göre sunulur. İlk nokta en erken dönem, son nokta ise en son veri toplama dönemidir.
Örnek:
{
"fractionTimeseries": {
"desktop": {"fractions": [0.3195, 0.2115, 0.1421]},
"phone": {"fractions": [0.6295, 0.7544, 0.8288]},
"tablet": {"fractions": [0.051, 0.0341, 0.029]}
}
}
Bu örnekteki en son veri noktası, sayfa yüklemelerinin% 14,21'inin masaüstünden, %82,88'inin ise telefonlardan geldiğini göstermektedir.
Metrik değeri türleri
CrUX History API aynı metrik değeri türlerini kullandığından daha fazla bilgi için günlük CrUX API metrik değer türleri dokümanlarına bakabilirsiniz.
Metrik uygunluğu
Uygunluk ölçütlerine bağlı olarak kaynak veya URL, CrUX History API kapsamındaki toplama dönemlerinin yalnızca bazıları için uygun olabilir. Bu durumlarda CrUX History API, histogramTimeseries
yoğunlukları için "NaN"
, uygun verisi olmayan toplama dönemleri içinse percentilesTimeseries
için null
değerini döndürür. Aradaki farkın nedeni, histogram yoğunluklarının her zaman sayı olmasıdır. yüzdelik dilimler ise sayı veya dize olabilir (CLS, sayı gibi görünse bile dizeleri kullanır).
Örneğin, ikinci dönemde herhangi bir uygun veri yoksa bu durum şu şekilde gösterilir:
{
"histogramTimeseries": [
{
"start": 0,
"end": 2500,
"densities": [0.9190, "NaN", 0.9194, 0.9195, 0.9183, 0.9187]
},
{
"start": 2500,
"end": 4000,
"densities": [0.0521, "NaN", 0.0518, 0.0518, 0.0526, 0.0527]
},
{
"start": 4000,
"densities": [0.0288, "NaN", 0.0286, 0.0285, 0.0290, 0.0285]
}
],
"percentilesTimeseries": {
"p75s": [1362, null, 1344, 1356, 1366, 1377]
},
}
Zaman içinde uygun olup olmamasına rağmen uygun olan URL'ler veya kaynaklar için birçok eksik giriş görebilirsiniz.
Toplama dönemleri
CrUX History API'si, her toplama penceresinin başlangıç ve bitiş tarihlerini temsil eden firstDate
ve endDate
alanlarından oluşan bir diziye sahip bir collectionPeriods
nesnesi içerir. Örneğin:
"collectionPeriods": [{
"firstDate": { "year": 2022, "month": 7, "day": 10 },
"lastDate": { "year": 2022, "month": 8, "day": 6 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 17 },
"lastDate": { "year": 2022, "month": 8, "day": 13 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 24 },
"lastDate": { "year": 2022, "month": 8, "day": 20 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 31 },
"lastDate": { "year": 2022, "month": 8, "day": 27 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 7 },
"lastDate": { "year": 2022, "month": 9, "day": 3 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 14 },
"lastDate": { "year": 2022, "month": 9, "day": 10 }
}
]
Bu toplama dönemleri artan düzendedir ve yanıtın diğer bölümlerindeki veri noktalarının her birinin tarih aralığını temsil eder.
History API her pazartesi güncellenir ve standart 2 günlük gecikmeye göre bir önceki cumartesi gününe kadar olan verileri içerir. Haftada bir toplama dönemi olacak şekilde önceki 25 haftalık verileri içerir.
Her toplama dönemi önceki 28 günlük birleştirilmiş verileri içerdiğinden ve toplama dönemleri haftalık olduğu için toplama dönemleri çakışır. Verilerin hareketli ortalamasına benzerler. Sonraki her döneme üç haftalık veri dahil edilir ve bir hafta farklıdır.
Örnek sorgular
Sorgular, POST gövdesinde JSON nesnesi olarak sorgu verilerine sahip https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]"
adresine bir POST isteği kullanılarak JSON nesneleri olarak gönderilir.
Günlük CrUX API'nin queryRecord
yerine queryHistoryRecord
kullanıldığına dikkat edin.
Örnek gövde aşağıdaki gibidir:
{
"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:queryHistoryRecord?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
interaction_to_next_paint
largest_contentful_paint
experimental_time_to_first_byte
navigation_types
round_trip_time
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 CrUX History API'yi kullanma kılavuzuna bakın.
Veri ardışık düzeni
CrUX veri kümesi, API aracılığıyla 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.
History API, her biri bu 28 günü kapsayan bir dizi toplama dönemi içerir. Her toplama dönemi önceki 28 günlük birleştirilmiş verileri içerdiğinden ve toplama dönemleri haftalık olduğu için toplama dönemleri çakışır. Verilerin hareketli ortalamasına benzerler. Sonraki her döneme üç haftalık veri dahil edilir ve bir hafta farklıdır.
Haftalık güncellemeler
History API her pazartesi 04:00 UTC civarında güncellenir ve standart 2 günlük gecikmeye göre bir önceki cumartesi gününe kadar olan verileri içerir. Haftada bir toplama dönemi olacak şekilde önceki 25 haftaya (yaklaşık 6 ay) ait verileri içerir.
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 History API'nin POST
HTTP isteğini kabul eden tek bir uç noktası 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:queryHistoryRecord
URL, gRPC Kod Dönüştürme söz dizimini kullanır.
İstek içeriği
CrUX History API, effectiveConnectionType
istek alanının desteklenmemesi durumu dışında günlük CrUX API ile aynı istek gövdelerini kullanır.
Örneğin, web.dev ana sayfası için masaüstü Largest Contentful Paint değerlerini istemek için:
{
"origin": "https://web.dev/",
"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": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogramTimeseries": [{
"start": 0, "end": 2500, "densities": [
0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187, ...
]
}, {
"start": 2500, "end": 4000, "densities": [
0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527, ...
]
}, {
"start": 4000, "densities": [
0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285, ...
]
}
],
"percentilesTimeseries": {
"p75s": [
1362, 1352, 1344, 1356, 1366, 1377, ...
]
}
}
},
"collectionPeriods": [{
"firstDate": { "year": 2022, "month": 7, "day": 10 },
"lastDate": { "year": 2022, "month": 8, "day": 6 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 17 },
"lastDate": { "year": 2022, "month": 8, "day": 13 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 24 },
"lastDate": { "year": 2022, "month": 8, "day": 20 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 31 },
"lastDate": { "year": 2022, "month": 8, "day": 27 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 7 },
"lastDate": { "year": 2022, "month": 9, "day": 3 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 14 },
"lastDate": { "year": 2022, "month": 9, "day": 10 }
}, {
...
}
]
}
}
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ü belirtilmemişse tüm form faktörlerinden toplanan 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 |
Kaynak, bu kaydın ait olduğu kaynağı belirtir. Not: Bir kaynak belirtilirken, tüm sayfalardaki bu kaynak altındaki yüklemelere ilişkin veriler, kaynak düzeyindeki kullanıcı deneyimi verileri olarak toplanır. |
url |
Not: |
Metrikler
metric
, ilk zengin içerikli boyama gibi tek bir web performansı metriği için kullanıcı deneyimi verilerinden oluşan bir gruptur. bins
serisindeki gerçek Chrome kullanımının özet histogramını içerir.
{
"histogramTimeseries": [
{
object (Bin)
}
],
"percentilesTimeseries": {
object (Percentiles)
}
}
veya
"fractionTimeseries": {
object (Fractions)
}
Alanlar | |
---|---|
histogramTimeseries[] |
Bir metrikle ilgili kullanıcı deneyimlerinin zaman serisi histogramı. Zaman serisi histogramı en az bir bölmeye sahip olur ve tüm bölmelerin yoğunlukları ~1'e eşit olur. Söz konusu Koleksiyon Dönemi için eksik değerler |
percentilesTimeseries |
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. Söz konusu Koleksiyon Dönemi için eksik değerler |
fractionTimeseries |
Bu nesne, etiketli kesirlerin zaman serilerini içeriyor. Bu sayı, giriş başına ~1'e eşittir. Kesirler, 4 ondalık basamak olacak şekilde yuvarlanır. Eksik girişler, tüm kesirlerde "NaN" olarak ifade edilir. |
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,
"densities": [number, number, number...etc.]
}
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. |
densities |
Belirli bir metrik için bu bölmenin değeriyle karşılaşan kullanıcıların oranının zaman serisi. 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 | |
---|---|
p75s |
Sayfa yüklemelerinin% 75'inin oluşturduğu değerlerin zaman serilerinde, belirtilen metrik bu değerde veya bu değerden daha düşük düzeydeydi. |
Kesirler
Fractions
, giriş başına ~1'e ulaşan etiketli kesirlerin zaman serisini içerir.
Her etiket sayfa yüklemesini bir şekilde açıkladığından metrikler bu şekilde gösterilir
sayısal değerler yerine ayrı değerler üretmek olarak düşünülebilir ve
kesirler, belirli bir farklı değerin ne sıklıkta ölçüldüğünü ifade eder.
{
"label_1": { "fractions": array[fraction]},
"label_1": { "fractions": array[fraction]},
...
"label_n": { "fractions": array[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. Metrik kullanılamadığında
bir tarih aralığı kullanıyorsanız ilgili giriş
"Yok" her kesirli dizede kullanılabilir.
Alanlar | |
---|---|
p75s |
Sayfa yüklemelerinin% 75'inin oluşturduğu değerlere ait zaman serilerinde, belirtilen metrik bu değerde veya bu değerden daha düşük düzeydeydi. |
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 History API, her iki API için de ücretsiz olarak sunulan Google Cloud projesi başına dakikada 150 sorguya yönelik CrUX API ile aynı sınırı paylaşır. 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.