CrUX Geçmişi API'si

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 Google Cloud API anahtarı gerekir. Günlük API ve geçmiş API'si için aynı anahtar kullanılabilir.

Kimlik bilgileri sayfasında bir tane oluşturabilir ve Chrome UX Report API kullanımı için bunun temel hazırlığını yapabilirsiniz.

Bir API anahtarınız olduktan sonra, uygulamanız tüm istek URL'lerine key=[YOUR_API_KEY] sorgu parametresini ekleyebilir. Örnek sorgular bölümüne 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ı 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 toplamaların zaman serileri (histogram, yüzdelik dilim ve kesir) halinde raporlarız.

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üklemelerinin yüzdesini temsil eder. 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 basit bir üç 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, bir sayfanın belirli bir şekilde yüklenmesini tanımlar. 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 istekte formFactor 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. Bu sözleşme her gün elinden gelenin en iyisi yapılarak gerçekleştirilir.

Ş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

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örlerinden toplanan veriler döndürülür.
Birleştirme alanı url_pattern. URL kalıbı, kaydın geçerli olduğu URL'dir. url_pattern şunlardan yalnızca biri olabilir:
origin

string

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

string

url, bu kaydın ait olduğu belirli bir URL'yi belirtir.

Not: url belirtirken yalnızca söz konusu URL'nin verileri toplanır.

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[]

object (Bin)

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 "NaN" olarak işaretlenir.
percentilesTimeseries

object (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.

Söz konusu Koleksiyon Dönemi için eksik değerler null olarak işaretlenir.
fractionTimeseries

object (Fractions)

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ş belirtilmemişse, 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

(integer | string)

Başlangıç, veri bölmesinin başlangıcıdır.
end

(integer | string)

Bitiş, veri bölmesinin sonudur. Bitiş doldurulmazsa, bölmenin sonu yoktur ve başlangıçtan +inf tarihine kadar geçerlidir.
densities

array[number]

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

array[(integer | string)]

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üklemeyi bir şekilde açıklar. Bu nedenle, bu şekilde temsil edilen metrikler, sayısal değerler yerine farklı değerler oluşturuyor olarak düşünülebilir. Kesirler ise 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 sayıdır 0.0 <= value <= 1.0 ve toplamları ~1,0'a eşittir. Metrik, belirli bir toplama dönemi için kullanılamadığında tüm kesir dizilerinde karşılık gelen giriş "NaN" olur.

Alanlar
p75s

array[(integer | string)]

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

string

Herhangi bir normalleştirme işleminden önce istenen orijinal URL.
normalizedUrl

string

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.