CrUX Geçmişi API'si

CrUX History API, sayfa ve kaynak ayrıntı düzeyinde altı aylık geçmiş gerçek kullanıcı deneyimi verilerine düşük gecikmeli erişim sağlar.

Yaygın kullanım alanı

CrUX History API, "https://example.com kaynağı için geçmiş kullanıcı deneyimi trendlerini öğrenin" gibi belirli bir URI'ye yönelik geçmiş kullanıcı deneyimi metriklerinin sorgulanmasına olanak tanır.

History API'si, günlük CrUX API ile aynı yapıyı izler. Tek fark, değerler bir dizide verilir ve anahtarlar çoğul adlarla etiketlenir (örneğin, histogram yerine histogramTimeseries veya p75 yerine p75s).

CrUX API Anahtarı

Günlük API'de olduğu gibi, CrUX History API'yi kullanabilmek için Google Cloud API anahtarı gerekir. Aynı anahtar, günlük ve geçmiş API'si için kullanılabilir.

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.

CrUX History API yalnızca form faktörü boyutuna göre toplanmış olarak kullanılabilir. PHONE, TABLET ve DESKTOP olarak ayrılan genel bir cihaz sınıfıdır.

Metrik

Metrikleri, istatistiksel toplamaların zaman serisi (histogram, yüzdelik dilim ve kesir) şeklinde 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 geldiği sayfa yüklemelerinin yüzdesini temsil eder. Veri noktaları, API tarafından döndürülen toplama dönemi tarihlerine göre sunulur. İlk nokta en erken dönem, son nokta ise en son veri toplama dönemi olacaktır.

Basit bir üç bin histogram örnek bir metrik 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, sayfa yüklemelerinin% 91,90'ında örnek metrik değerinin, geçmişteki ilk toplama dönemi için 0 ms ile 2.500 ms. arasında ve ardından %92,03, %91,94... Metriğin birimleri bu histogramda yer almıyor. Bu durumda, milisaniye olduğu varsayılır.

Ayrıca, geçmişteki ilk veri toplama döneminde sayfa yüklemelerinin% 5,21'inde örnek metrik değeri 2.500 ms. ile 4.000 ms. arasında ve sayfa yüklemelerinin% 2,88'inde ilk veri toplama döneminde 4.000 ms.den daha yüksek bir değer görülmüştür.

Yüzdelik dilimler

Metrikler, ek analiz için yararlı olabilecek yüzdelik dilimlerin zaman serisini de içerebilir.

Veri noktaları, API tarafından döndürülen toplama dönemi tarihlerine göre sunulur. İlk nokta en erken dönem, son nokta ise en son veri toplama dönemi olacaktır.

{
  "percentilesTimeseries": {
    "p75s": [1362, 1352, 1344, 1356, 1366, 1377]
  },
}

Bu yüzdelik dilimler, söz konusu metrik için verilen yüzdelik dilimdeki belirli metrik değerlerini gösterebilir. Bunlar, nihai birleştirilmiş veri kümesine değil, kullanılabilir verilerin tamamına dayanır. Bu nedenle, nihai birleşik histograma dayanan interpolasyon yüzdelik dilimiyle eşleşmek zorunda değildirler.

Kesirler

Metrikler, etiketli kesirlerin zaman serisi olarak ifade edilebilir; her etiket bir sayfa yüklemesini belirli bir şekilde tanımlar. Veri noktaları, API tarafından döndürülen toplama dönemi tarihlerine göre sunulur. İlk nokta en erken dönem, son nokta ise en son veri toplama dönemi olacaktır.

Ö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 örnekte en son veri noktası, sayfa yüklemelerinin% 14,21'inin masaüstünden, %82,88'inin ise telefonlardan geldiğini göstermektedir.

Metrik değer türleri

CrUX History API aynı metrik değer türlerini kullandığından daha fazla bilgi için günlük CrUX API metrik değer türleri belgelerine bakabilirsiniz.

Metrik uygunluğu

Uygunluk ölçütlerine göre kaynak veya URL, yalnızca CrUX History API kapsamındaki toplama dönemlerinden bazıları için uygun olabilir. Böyle durumlarda CrUX History API, uygun verisi olmayan toplama dönemleri için histogramTimeseries yoğunlukları için "NaN", percentilesTimeseries için de null döndürür. Farkın nedeni, histogram yoğunluklarının her zaman sayı olmasıdır. Yüzdelik dilimler ise sayılar veya dizeler olabilir (CLS, sayı gibi görünseler bile dize kullanır).

Örneğin, ikinci dönemde uygun veriler yoksa bu durum aşağıdaki gibi 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 duruma gelen veya uygun olmayan URL'ler ya da kaynaklar için birçok girişin eksik olduğunu fark edebilirsiniz.

Toplama dönemleri

CrUX History API, 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 her bir veri noktasının tarih aralığını temsil eder.

History API her Pazartesi güncellenir ve önceki Cumartesi gününe kadar olan verileri içerir (standart 2 günlük gecikme uyarınca). Önceki 25 haftanın verilerini içerir (haftada bir toplama dönemi).

Her toplama dönemi önceki 28 günlük birleştirilmiş verileri içerdiği ve toplama dönemleri haftalık olduğu için toplama dönemleri çakışacaktır. Bunlar, verilerin hareketli ortalamasına benzer. Üç haftalık veri, takip eden her döneme dahil edilir ve bir hafta farklıdır.

Örnek sorgular

Sorgular, https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?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 kullanılır.

Günlük CrUX API'sinin queryRecord yerine queryHistoryRecord kullanıldığını unutmayın.

Örnek gövde:

{
  "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: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ü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
  • interaction_to_next_paint
  • largest_contentful_paint
  • experimental_time_to_first_byte
  • navigation_types
  • form_factors (yalnızca istekte formFactor 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 CrUX History API'yi kullanma kılavuzuna bakın.

Veri ardışık düzeni

CrUX veri kümesi, verileri API üzerinden kullanılabilir hale gelmeden önce 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.

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ği ve toplama dönemleri haftalık olduğu için toplama dönemleri çakışacaktır. Bunlar, verilerin hareketli ortalamasına benzer. Üç haftalık veri, takip eden her döneme dahil edilir ve bir hafta farklıdır.

Haftalık güncellemeler

History API her pazartesi saat 04:00 UTC civarında güncellenir ve önceki cumartesi gününe kadar olan verileri içerir (standart 2 günlük gecikme uyarınca). Haftada bir toplama dönemi olacak şekilde önceki 25 haftaya ait (yaklaşık 6 ay) verileri içerir.

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 History 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: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 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 üzere:

{
  "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 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": {
      "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örleri üzerinden birleştirilmiş veriler döndürülür.
Birleştirme alanı url_pattern. URL kalıbı, kaydın uygulandığı URL'dir. url_pattern şunlardan yalnızca biri olabilir:
origin

string

Kaynak, bu kaydın ait olduğu kaynağı belirtir.

Not: Bir kaynak belirtirken, bu kaynak altında tüm sayfalardaki yükleme verileri kaynak düzeyindeki kullanıcı deneyimi verileri olarak birleştirilir.
url

string

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

Not: url belirtilirken yalnızca bu belirli URL için veriler toplanır.

Metrikler

metric, ilk zengin içerikli boyama gibi tek bir web performansı metriğine ait kullanıcı deneyimi verileri grubudur. Burada, bir bins serisi olarak 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 metriğe ait kullanıcı deneyimlerinin zaman serisi histogramı. Zaman serisi histogramında en az bir bölme bulunur ve tüm bölmelerin yoğunluklarının toplamı yaklaşık 1 olur.

Söz konusu Koleksiyon Dönemi'ne ait eksik değerler "NaN" olarak işaretlenir.
percentilesTimeseries

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

Söz konusu Koleksiyon Dönemi'ne ait eksik değerler null olarak işaretlenir.
fractionTimeseries

object (Fractions)

Bu nesne, giriş başına yaklaşık 1'e eşit olan etiketli kesirlerin zaman serisi içeriyor.

Kesirler, 4 ondalık basamağa yuvarlanır.

Eksik girişler, tüm kesirlerde"NaN" olarak ifade edilir.

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,
  "densities": [number, number, number...etc.]
}
Alanlar
start

(integer | string)

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

(integer | string)

Bitiş, veri bölmesinin sonudur. Bitiş alanı doldurulmazsa bölmenin sonu yoktur ve başlangıcından +sona kadar geçerli olur.
densities

array[number]

Belirli bir metrik için bu bölmenin değerini yaşayan kullanıcıların oranının zaman serisi.

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
p75s

array[(integer | string)]

Sayfa yüklemelerinin% 75'inde gerçekleşen değer zaman serisi, belirtilen metrikle bu değerde veya daha düşük bir değerle deneyimlendi.

Kesirler

Fractions, giriş başına toplamı yaklaşık 1 olan etiketli kesirlerin zaman serilerini içerir. 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 oluşturuyormuş gibi 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 çok benzer şekilde, her fraction bir 0.0 <= value <= 1.0 sayıdır ve toplamı yaklaşık 1, 0'dır. 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'inde gerçekleşen değerlerin zaman serisi, belirtilen metrikle bu değerde veya bu değerden daha düşük performans gösterdi.

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

string

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

string

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 History API, her iki API için de ücretsiz olarak sunulan Google Cloud projesi başına dakikada 150 sorgu için CrUX API ile aynı sınırı paylaşı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.