CrUX API'si

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

Deneyin.

Yaygın kullanım alanı

CrUX API, "https://example.com kaynağının metriklerini al" gibi belirli bir URI için kullanıcı deneyimi metriklerinin sorgulanmasına olanak tanır.

CrUX API anahtarı

CrUX API'yi kullanmak için Chrome UX Report API kullanımı için hazırlanmış bir Google Cloud API anahtarı gerekir.

API anahtarı edinme ve kullanma

Anahtar alma

veya 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üne bakın.

Veri modeli

Bu bölümde, isteklerdeki 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ıtta bir veya daha fazla metriğe ait veriler bulunabilir.

Tanımlayıcılar

Tanımlayıcılar, hangi kayıtların aranacağını belirtir. CrUX'ta 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ğının şu 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 ayarlayarak sorgularken http://www.example.com/, http://www.example.com/foo.html ve http://www.example.com/bar.html sayfalarına ait verilerin, bu kaynak altındaki tüm sayfalar oldukları için birlikte toplanmış şekilde döndürüleceği anlamına gelir.

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 bakalım:

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 ilgili sayfanın verileri döndürülür.

Boyutlar

Boyutlar, bir kaydın toplandığı belirli bir veri grubunu tanımlar. Örneğin, PHONE biçim 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 vardır ve bu boyutun belirtilmemesi, boyutun tüm değerler üzerinden toplandığı anlamına gelir. Örneğin, form faktörü belirtilmemişse kaydın herhangi bir form faktöründe gerçekleşen yüklemelerle ilgili bilgi içerdiği anlaşılır.

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.

Metrik

Metrikleri histogramlar, yüzdelikler ve kesirler halinde istatistiksel toplama olarak raporlarız.

Kayan noktalı değerler 4 ondalık basamağa yuvarlanır (cumulative_layout_shift metriklerinin dize olarak kodlanmış çiftler olduğunu, dolayısıyla kayan noktalı sayı olarak kabul edilmediğini ve dize içinde 2 ondalık basamak halinde raporlandığını unutmayın).

Histogram

Metrikler bir histogramda ifade edildiğinde, ilgili metrik için belirli aralıklara giren sayfa yüklemelerinin yüzdelerini gösteririz.

Örnek bir metrik için üç binlik bir 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 0 ms ile 1.000 ms arasında ölçüldüğünü gösterir. Metrik birimleri bu histogramda yer almaz. Bu durumda milisaniye olduğunu varsayacağız.

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üzdelik dilim

Metrikler, ek analizler için yararlı olabilecek yüzdelik dilimleri de içerebilir. Belirli metrik değerlerini, ilgili metrik için belirtilen yüzdelik dilimde bildiririz. Bunlar, nihai gruplandırılmış verileri değil, mevcut verilerin tamamını temel alır. Bu nedenle, nihai gruplandırılmış histograma dayalı bir enterpolasyonlu yüzdeyle eşleşmeyebilir.

{
  "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 etiketlenebilen sayfa yüklemelerinin yüzdelerini gösterir. Bu durumda metrik değerleri bu etiketlerdir.

Örneğin, form_factors metriği, belirli bir 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çüldü. Böylece toplam% 100'e ulaşıldı.

Metrik değer türleri

CrUX API Metrik Adı Veri Türü Metrik Birimler İstatistiksel Toplamalar Belgeler
cumulative_layout_shift 2 ondalık basamaklı, dize olarak çift kodlanmış birimsiz Üç bölmeli histogram, p75 ile yüzdelik dilim cls
first_contentful_paint int milisaniye Üç bölmeli histogram, p75 ile yüzdelik dilim fcp
interaction_to_next_paint int milisaniye Üç bölmeli histogram, p75 ile yüzdelik dilim inp
largest_contentful_paint int milisaniye Üç bölmeli histogram, p75 ile yüzdelik dilim lcp
experimental_time_to_first_byte int milisaniye Üç bölmeli histogram, p75 ile yüzdelik dilim ttfb
form_factors 4 ondalık basamaklı çift yüzde form faktöründen kesre eşleme form faktörleri
navigation_types 4 ondalık basamaklı çift yüzde Gezinme türünden kesre eşleme gezinme türleri
round_trip_time int milisaniye p75 ile yüzdelik dilimler rtt

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
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ına sahip bir collectionPeriod nesnesi içerir. Örneğin:

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }

Bu sayede verileri ve ilgili gün için henüz güncellenip güncellenmediğini ya da dünkü verileri döndürüp döndürmediğini daha iyi anlayabilirsiniz.

CrUX API'nin, günün tamamlanmış verilerini beklediği ve API'de kullanılabilmesi için biraz işlem süresi gerektiği için bugünün tarihinden yaklaşık iki gün geride olduğunu unutmayın. Kullanılan saat dilimi Pasifik Standart Saati'dir (PST) ve yaz saati uygulamasında herhangi bir değişiklik yoktur.

Ayrıca, veriler 28 günün tamamına ait olmasa bile (örneğin, bir sayfa 28 günden kısa bir süre önce yayınlanmışsa) collectionPeriod her zaman 28 gün gösterir. collectionPeriod, CrUX verilerinin toplandığı dönemdir, verilerin temsil ettiği dönem olmayabilir.

Örnek sorgular

Sorgular, https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" adresine POST isteği gönderilerek JSON nesnesi olarak gönderilir. Sorgu verileri, POST gövdesinde JSON nesnesi olarak gönderilir:

{
  "origin": "https://example.com",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

Örneğin, bu komut aşağıdaki komut satırıyla curl adresinden çağrılabilir (API_KEY, anahtarınızla değiştirilir):

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, sorguda origin yerine url mülkü iletilerek API üzerinden kullanılabilir:

{
  "url": "https://example.com/page",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

metrics mülkü ayarlanmazsa mevcut tüm metrikler döndürülür:

  • cumulative_layout_shift
  • first_contentful_paint
  • 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örlerinde toplanır.

Daha fazla örnek sorgu için Chrome Kullanıcı Deneyimi Raporu API'sini kullanma başlıklı makaleyi inceleyin.

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 üzerinden işlenir.

Hareketli ortalama

Chrome kullanıcı deneyimi raporundaki veriler, birleştirilmiş 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 toplanmış hali olduğu anlamına gelir.

Bu, BigQuery'deki CrUX veri kümesinin aylık raporları toplamasına benzer.

Günlük güncellemeler

Veriler her gün UTC 04:00 civarında güncellenir. Güncelleme süreleri için hizmet düzeyi sözleşmesi yoktur. Güncelleme her gün mümkün olduğunca yapılır.

Şema

CrUX 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: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 veriler 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

enum (FormFactor)

Form faktörü, kaydın verilerinin ait olması gereken cihaz sınıfını belirten bir sorgu boyutudur.

Bu alanda DESKTOP, PHONE veya TABLET değerleri kullanılır.

Not: Form faktörü belirtilmezse tüm form faktörleri için birleştirilmiş veriler içeren özel bir kayıt döndürülür.
metrics[]

string

Yanıta dahil edilmesi gereken metrikler. Hiçbiri belirtilmezse bulunan tüm metrikler döndürülür.

İzin verilen değerler: ["cumulative_layout_shift", "first_contentful_paint", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]
Birlik alanı url_pattern. url_pattern, kayıt arama işleminin ana tanımlayıcısıdır. Yalnızca aşağıdakilerden biri olabilir:
origin

string

url_pattern "origin", bir web sitesinin kaynağı olan URL kalıbını ifade eder.

Örnekler: "https://example.com", "https://cloud.google.com"
url

string

url_pattern url, herhangi bir URL olan bir URL kalıbını ifade eder.

Örnekler: "https://example.com/, https://cloud.google.com/why-google-cloud/"

Örneğin, Chrome geliştirici dokümanları ana sayfası için masaüstündeki en büyük Largest Contentful Paint değerlerini istemek üzere:

{
  "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 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 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

enum (FormFactor)

Form faktörü, bu kayıt için siteye erişmek üzere tüm kullanıcıların kullandığı cihaz sınıfıdır.

Form faktörü belirtilmezse tüm form faktörleri için birleştirilmiş veriler döndürülür.
Birlik alanı url_pattern. URL kalıbı, kaydın geçerli olduğu URL'dir. url_pattern yalnızca aşağıdakilerden biri olabilir:
origin

string

origin, bu kaydın hangi kaynak için olduğunu belirtir.

Not: Bir origin belirtilirken, tüm sayfalardaki bu kaynak altındaki yüklemelerle ilgili veriler kaynak düzeyinde kullanıcı deneyimi verileri olarak toplanır.
url

string

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

Not: url belirtilirken yalnızca söz konusu URL'ye ait veriler toplanır.

Metrikler

metric, ilk zengin içerikli boyama gibi tek bir web performansı metriği için toplanmış kullanıcı deneyimi verilerinden oluşan bir gruptur. Gerçek dünyadaki Chrome kullanımının özet histogramını bins dizisi olarak, belirli yüzdelik verileri (ör. p75) veya etiketli kesirleri içerebilir.

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

veya

{
  "fractions": {
    object (Fractions)
  }
}
Alanlar
histogram[]

object (Bin)

Bir metrik için kullanıcı deneyimlerinin histogrami. Histogramda en az bir kutu bulunur ve tüm kutuların yoğunlukları yaklaşık 1'e eşittir.
percentiles

object (Percentiles)

Metrik için yaygın olarak kullanılan yüzdelik dilimler. Yüzdelik dilimlerin değer türü, histogram paketleri için verilen değer türleriyle aynı olur.
fractions

object (Fractions)

Bu nesne, toplamı yaklaşık 1 olan etiketli kesirler içerir.

Kesirler 4 ondalık basamak olacak şekilde yuvarlanır.

Bölme

bin, başlangıçtan sona kadar veya bitiş belirtilmemişse başlangıçtan pozitif sonsuzluk değerine kadar olan verilerin ayrık bir bölümüdür.

Bir grubun 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 kapsayıcılarında başlangıç ve bitiş türleri için int32 kullanılı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 kapları değer türü için dizeler kullanır.

{
  "start": value,
  "end": value,
  "density": number
}
Alanlar
start

(integer | string)

Başlangıç, veri grubunun başlangıcıdır.
end

(integer | string)

Bitiş, veri grubunun sonudur. end doldurulmamışsa bin'in bitiş değeri yoktur ve başlangıçtan +inf değerine kadar geçerlidir.
density

number

Belirtilen metrik için bu grubun değerini deneyimleyen kullanıcıların oranı.

Yoğunluklar 4 ondalık basamağa yuvarlanır.

Yüzdelik dilim

Percentiles, belirli bir istatistiksel yüzdelik dilimdeki bir metriğin sentetik değerlerini içerir. Bunlar, bir metriğin değerini toplam kullanıcı sayısı içindeki kullanıcı yüzdesinin deneyimlediği şekilde tahmin etmek için kullanılır.

{
  "P75": value
}
Alanlar
p75

(integer | string)

Sayfa yüklemelerinin% 75'inde, belirli metrik bu değerde veya bu değerin altındaydı.

Kesirler

Fractions, toplamı yaklaşık 1 olan etiketli kesirler içerir. Her etiket bir sayfa yüklemesini bir şekilde tanımlar. Bu nedenle, bu şekilde temsil edilen metriklerin sayısal değerler yerine farklı değerler ürettiği düşünülebilir. Kesirler ise belirli bir farklı değerin ne sıklıkta ölçüldüğünü ifade eder.

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

Histogram kaplarındaki yoğunluk değerlerine benzer şekilde, her fraction bir sayı 0.0 <= value <= 1.0'dır ve toplamları yaklaşık 1, 0'dur.

UrlNormalization

Daha yüksek bir başarılı arama şansı elde etmek için bir URL'yi normalleştirmek üzere gerçekleştirilen normalleştirme işlemlerini temsil eden nesne. Bunlar, sağlanan url_pattern başarısız olduğunda yapılacak basit otomatik değişikliklerdir. Yönlendirmeleri takip etme gibi karmaşık işlemler ele alınmaz.

{
  "originalUrl": string,
  "normalizedUrl": string
}
Alanlar
originalUrl

string

Normalleştirme işlemleri yapılmadan önce istenen orijinal URL.
normalizedUrl

string

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 dakika başına 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 geniş kota, kullanım alanlarının büyük çoğunluğu için yeterli olacaktır. Daha yüksek kota için ödeme yapmak mümkün değildir.