CrUX API'si

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

Deneyin.

Yaygın kullanım alanı

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

CrUX API anahtarı

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

API anahtarı edinme ve kullanma

veya Kimlik Bilgileri sayfasında bir tane oluşturun.

API anahtarınız olduktan sonra uygulamanız, sorgu parametresi key=yourAPIKey'yı 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ünü inceleyin.

Veri modeli

Bu bölümde, istek ve yanıtlardaki verilerin yapısı ayrıntılı olarak açıklanmaktadır.

Kaydet

Bir sayfa veya site hakkında ayrı bir bilgi parçası. Bir kayıtta, bir tanımlayıcıya ve belirli bir boyut kombinasyonuna özgü veriler bulunabilir. Bir kayıt, bir veya daha fazla metrikle ilgili veriler içerebilir.

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, bu kaynaktaki tüm sayfalara ait tüm veriler birlikte toplanır. Örneğin, http://www.example.com kaynağında bu site haritasında belirtildiği gibi sayfalar olduğunu varsayalım:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Bu, kaynak http://www.example.com olarak ayarlanmış şekilde Chrome UX Report sorgulandığında http://www.example.com/, http://www.example.com/foo.html ve http://www.example.com/bar.html ile ilgili verilerin birleştirilerek döndürüleceği anlamına gelir. Çünkü bu sayfaların tümü söz konusu kaynağın altındadır.

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 bakarsak:

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 o sayfanın verileri 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 bilgiler içerdiğini gösterir. Her boyutun belirli sayıda değeri vardır ve bu boyutun belirtilmemesi, boyutun tüm değerler üzerinde toplandığı anlamına gelir. Örneğin, form faktörü belirtilmemesi, kaydın herhangi bir form faktöründe gerçekleşen yüklemelerle ilgili bilgiler 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ılan genel bir cihaz sınıfıdır.

Metrik

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

Kayan nokta değerleri 4 ondalık basamağa yuvarlanır (cumulative_layout_shift metriklerinin dize olarak kodlanmış çiftler olduğu için kayan nokta olarak kabul edilmediğini ve dize içinde 2 ondalık basamağa yuvarlanarak raporlandığını unutmayın).

Histogram

Metrikler histogramda gösterildiğinde, ilgili metrik için belirli aralıklara giren sayfa yükleme yüzdelerini gösteririz.

Örnek bir metrik için üç kutulu histogram şu şekilde 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. Metriğin birimleri bu histogramda yer almıyor. Bu durumda milisaniye olarak kabul edeceğiz.

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üzdelikler

Metrikler, ek analizler için yararlı olabilecek yüzdelik dilimler de içerebilir. Belirli metrik değerlerini, ilgili metrik için belirtilen yüzdelik dilimde raporlarız. Bu değerler, nihai gruplandırılmış verileri değil, mevcut verilerin tamamını temel alır. Bu nedenle, nihai gruplandırılmış histogramı temel alan bir enterpolasyonlu yüzdelik dilimle 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 etiketlenebilecek 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çülerek toplamda% 100'e ulaşılmıştır.

Metrik değer türleri

BigQuery metrik adı eşleme

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

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

Bu sayede veriler daha iyi anlaşılır ve verilerin o gün için güncellenip güncellenmediği veya dünkü verilerin aynısını döndürüp döndürmediği anlaşılır.

Toplama dönemi PageSpeed Insights'ta da mevcuttur:

Ayrıca, veriler 28 günün tamamını kapsamasa bile (örneğin, bir sayfa 28 günden daha kısa bir süre önce yayınlandıysa) collectionPeriod her zaman 28 günü gösterir. collectionPeriod, CrUX verilerinin toplandığı dönemdir. Verilerin temsil ettiği dönem olması gerekmez.

Örnek sorgular

Sorgular, POST gövdesinde JSON nesnesi olarak sorgu verileriyle birlikte https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" adresine 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 işlev curl üzerinden aşağıdaki komut satırıyla çağrılabilir (API_KEY yerine anahtarınızı girin):

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 verilere, sorguda origin yerine url mülkü iletilerek API aracılığıyla erişilebilir:

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

metrics özelliği 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
• largest_contentful_paint_resource_type
• largest_contentful_paint_image_time_to_first_byte
• largest_contentful_paint_image_resource_load_delay
• largest_contentful_paint_image_resource_load_duration
• largest_contentful_paint_image_element_render_delay
• navigation_types
• round_trip_time
• form_factors (yalnızca istekte formFactor belirtilmemişse raporlanır)
• experimental_ad_count (yalnızca reklam metriklerine dahil edilen sayfalar için raporlanır)
• experimental_ad_density (yalnızca reklam metriklerine dahil edilen sayfalar için raporlanır)
• experimental_ad_cpu (yalnızca reklam metriklerine dahil edilen sayfalar için raporlanır)
• experimental_ad_kilobytes (yalnızca reklam metriklerine dahil edilen sayfalar için 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ılabilir hale gelmeden önce verileri birleştirmek, toplamak ve filtrelemek için bir işlem hattı üzerinden işlenir.

Hareketli ortalama

Chrome UX Raporu'ndaki veriler, toplu metriklerin 28 günlük hareketli ortalamasıdır. Bu nedenle, Chrome UX Report'ta herhangi bir zamanda sunulan veriler aslında son 28 güne ait, birlikte toplanmış verilerdir.

Bu, BigQuery'deki CrUX veri kümesinin aylık raporları toplama şekline 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. Güncelleme her gün en iyi çaba temelinde çalıştırılır.

Şema

CrUX API'nin POST HTTP isteklerini 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:queryRecord

URL, gRPC Kod Dönüştürme söz dizimini kullanır.

İstek metni

İstek içeriği aşağıdaki yapıyla birlikte verileri 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.
}

Örneğin, Chrome geliştirici belgeleri ana sayfası için masaüstü Largest Contentful Paint değerlerini istemek üzere:

{
  "url": "https://developer.chrome.com/docs/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

Yanıt metni

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 şekilde 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.
}

Metrikler

metric, tek bir web performansı metriği (ör. ilk zengin içerikli boyama) için toplu kullanıcı deneyimi verileri kümesidir. Gerçek dünyadaki Chrome kullanımının özet histogramını bir dizi bins, belirli yüzdelik dilim verisi (ör. p75) olarak içerebilir veya etiketli kesirler içerebilir.

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

veya

{
  "fractions": {
    object (Fractions)
  }
}

Bölme

bin, başlangıçtan bitişe kadar uzanan veya bitiş belirtilmemişse başlangıçtan pozitif sonsuza kadar uzanan ayrı bir veri parçasıdır.

Bir aralığın başlangıç ve bitiş değerleri, temsil ettiği metriğin değer türünde verilir. Örneğin, First Contentful Paint milisaniye cinsinden ölçülür ve tam sayı olarak gösterilir. Bu nedenle, metrik grupları başlangıç ve bitiş türleri için int32'leri kullanı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 grupları değer türü için dizeleri kullanır.

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

Yüzdelikler

Percentiles, belirli bir istatistiksel yüzdelik dilimdeki bir metriğin yapay değerlerini içerir. Bunlar, bir metriğin değerini toplam kullanıcı sayısının belirli bir yüzdesi tarafından deneyimlendiği şekilde tahmin etmek için kullanılır.

{
  "P75": value
}

Kesirler

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

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

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

UrlNormalization

Başarılı bir arama ş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 başarısız olacağı bilindiğinde yapılan temel, otomatik değişikliklerdir. Yönlendirmeleri takip etme gibi karmaşık işlemler gerçekleştirilmez.

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

Hız sınırları

CrUX API, Google Cloud projesi başına dakikada 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 yüksek kota, kullanım alanlarının büyük çoğunluğu için yeterli olmalıdır. Kota artışı için ödeme yapmak mümkün değildir.