CrUX History API nasıl kullanılır?

Johannes Henkel

Jasmine Yan

Barry Pollard

Yayınlanma tarihi: 7 Şubat 2023, Son güncelleme tarihi: 11 Nisan 2025

Bu kılavuzda, web performansı verilerinin zaman serilerini sağlayan Chrome Kullanıcı Deneyimi Raporu (CrUX) Geçmişi API uç noktası tanıtılmaktadır. Bu veriler haftalık olarak güncellenir ve bir haftalık aralıklarla dağıtılmış 40 veri noktasıyla yaklaşık 6 aylık geçmişi görmenizi sağlar.

Orijinal CrUX API uç noktasından gelen günlük güncellemelerle birlikte kullanıldığında, artık hem en son verileri hem de daha önce olanları hızlı bir şekilde görebilirsiniz. Bu da zaman içindeki web sayfası değişikliklerini görmenizi sağlayan güçlü bir araçtır.

Bu sayfada API'yi deneyin

Deneyin.

Günlük CrUX API'sini sorgulama

CrUX API ile ilgili önceki bir makalede özetlediğimiz gibi, belirli bir kaynak için alan verilerinin anlık görüntüsünü şu şekilde alabilirsiniz:

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" --header 'Content-Type: application/json' --data '{"origin": "https://web.dev"}'

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [{
          "start": 0, "end": 2500, "density": 0.9192
        }, {
          "start": 2500, "end": 4000, "density": 0.0513
        }, {
          "start": 4000, "density": 0.0294
        }],
        "percentiles": {
          "p75": 1303
        }
      }
      // ...
    },
    "collectionPeriod": {
      "firstDate": { "year": 2022, "month": 12, "day": 27 },
      "lastDate": { "year": 2023, "month": 1, "day": 23 }
    }
  }
}

Bu anlık görüntü, belirli bir 28 günlük toplama dönemine (bu örnekte 27 Aralık 2022 - 23 Ocak 2023) ait histogram yoğunluğu değerlerini ve yüzdelik değerlerini içerir.

CrUX History API'yi sorgulama

Geçmiş uç noktasını çağırmak için URL'deki queryRecord değerini curl komutundaki queryHistoryRecord olarak değiştirin. Önceki çağrı için kullanılan CrUX API anahtarını kullanmak işe yarayacaktır. collectionPeriodCount, döndürülecek zaman serisi girişlerinin sayısını belirtir. Maksimum değer 40'tır. Belirtilmezse varsayılan olarak 25 olur.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
 --header 'Content-Type: application/json' \
 --data '{"origin": "https://web.dev", "collectionPeriodCount": 40}'

Yanıtın genel şekli benzerdir ancak çok daha fazla veri vardır. Artık tek bir veri noktası yerine, 75. yüzdelik dilim (p75) ve histogram yoğunluğu değerlerini içeren alanlar için zaman serileri var.

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

Bu örnekte, Largest Contentful Paint (LCP) metriğinin 0-2.500 ms aralığı için densities zaman serisi [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].'dir. Bu yoğunlukların her biri, ilgili collectionPeriods girişi sırasında gözlemlenmiştir. Örneğin, beşinci yoğunluk olan 0,9183, 3 Eylül 2022'de sona eren beşinci toplama döneminin yoğunluğuydu. 0,9187 ise bundan sonraki haftanın sonunda sona eren dönemin yoğunluğuydu.

Başka bir deyişle, https://web.dev örneğindeki son zaman serisi girişleri yorumlandığında 14 Ağustos 2022 ile 10 Eylül 2022 arasında sayfa yüklemelerinin% 91,87'sinin LCP değerlerinin 2.500 ms'den küçük, %5,27'sinin 2.500 ms ile 4.000 ms arasında ve% 2,85'inin 4.000 ms'den büyük olduğu tespit edildi.

Benzer şekilde, p75 değerleri için de bir zaman serisi vardır: 14 Ağustos 2022'den 10 Eylül 2022'ye kadar olan LCP p75 değeri 1377 idi. Bu, söz konusu toplama döneminde kullanıcı deneyimlerinin% 75'inin 1.377 ms'den kısa bir LCP'ye, %25'inin ise 1.377 ms'den uzun bir LCP'ye sahip olduğu anlamına gelir.

Örnekte yalnızca 6 zaman serisi girişi ve toplama dönemi listelenmiş olsa da API'den gelen yanıtlarda varsayılan olarak 25 zaman serisi girişi ve istekte "collectionPeriodCount": 40 belirtildiğinde en fazla 40 giriş bulunur. Bu toplama dönemlerinin her birinin bitiş tarihi, 7 gün arayla gelen cumartesi günleri olduğundan "collectionPeriodCount": 40 ile 10 ay kapsanır.

Not: Günlük API'nin aksine, CrUX History API yalnızca haftada bir kez Pazartesi günleri güncellenir (önceki Cumartesi gününe kadar olan veriler dahil). Ancak günlük API'de olduğu gibi, CrUX History API'deki her değer de önceki 28 gün içinde ölçülür. Bu nedenle, History API, belirli bir tarih için günlük API kullanılarak kullanılabilen verileri temsil etmelidir. Bu veriler artık geriye dönük olarak sorgulanabilir. Ancak bu, History API'nin çakışan veri dönemleri içerdiği anlamına gelir. Trend analizi olarak, metriklerdeki zaman içindeki değişimi izlemek için yararlıdır.

Belirli bir yanıtta, histogram bin yoğunlukları ve p75 değerleri için zaman serisinin uzunluğu, collectionPeriods alanındaki dizinin uzunluğuyla tam olarak aynı olur. Bu dizilerdeki indekse göre bire bir eşleşme vardır.

Sayfa düzeyindeki verileri sorgulama

CrUX History API, kaynak düzeyindeki verilerin yanı sıra geçmiş sayfa düzeyindeki verilere de erişim sağlar. Kaynak düzeyindeki veriler daha önce BigQuery'deki CrUX veri kümesi kullanılarak kullanılabilirken sayfa düzeyindeki geçmiş veriler yalnızca siteler verileri kendileri toplayıp depoladığında kullanılabilirdi. Yeni API, artık bu geçmiş sayfa düzeyindeki verilerin kilidini açıyor.

Sayfa düzeyindeki veriler aynı şekilde sorgulanabilir ancak yükte origin yerine url kullanılır:

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
 --header 'Content-Type: application/json' \
 --data '{"url": "https://web.dev/blog/"}'

Sayfa düzeyindeki (ve kaynak düzeyindeki) geçmiş veriler, CrUX'un geri kalanıyla aynı uygunluk koşullarına tabidir. Bu nedenle, belirli sayfalarda eksiksiz bir geçmiş kaydı olmayabilir. Bu durumlarda, "eksik" veriler histogramTimeseries yoğunlukları için "NaN", percentilesTimeseries için null ile gösterilir. Farkın nedeni, histogram yoğunluklarının her zaman sayı olması, yüzdelik dilimlerin ise sayı veya dize olabilmesidir (CLS, sayı gibi görünseler bile dizeleri kullanır).

Verileri görselleştirme

Verileri görselleştirmenin en kolay yolu, CrUX History API'nin gücünü göstermek için özel olarak oluşturulmuş bir araç olan CrUX Vis'tir. Daha fazla bilgi için CrUX Vis belgelerini inceleyin.

Benzer grafikleri kendiniz oluşturmak için örnek bir Colab oluşturduk. Colab veya "Colaboratory", tarayıcınızda Python yazmanıza ve yürütmenize olanak tanır. CrUX History API Colab (kaynak), API'ye çağrı yapmak ve verileri grafiklendirmek için Python'u kullanır.

Bu Colab, kısa bir formu doldurarak p75 grafikleri ve üçlü bin grafikleri oluşturmanıza, verileri tablo biçiminde almanıza ve CrUX API için istek ve yanıt çiftini görmenize olanak tanır. Bu aracı kullanmak için programcı olmanız gerekmez. Ancak Python koduna göz atabilir ve kodu harika bir şeye dönüştürebilirsiniz. İyi eğlenceler dileriz. Gördüğünüz içeriklerle ilgili geri bildirimlerinizi bizimle paylaşabilirsiniz.

Elbette Colab veya Python ile sınırlı değilsiniz. Bu, yeni API'yi kullanmanın yalnızca bir örneğidir. API, JSON tabanlı bir HTTP uç noktası olduğundan herhangi bir teknolojiden sorgulanabilir.

Sonuç

CrUX History API uç noktası kullanıma sunulmadan önce site sahipleri, CrUX'ten elde edebilecekleri geçmiş bilgiler konusunda sınırlıydı. BigQuery kullanılarak aylık kaynak düzeyinde veriler elde edilebiliyordu ancak haftalık veriler ve sayfa düzeyinde geçmiş veriler elde edilemiyordu. Site sahipleri bu verileri günlük API'yi kullanarak kendileri kaydedebilir ancak genellikle bu ihtiyaç yalnızca metriklerde gerileme yaşandıktan sonra fark edilir.

Bu CrUX Geçmişi API'sinin kullanıma sunulmasıyla birlikte, site sahiplerinin değişen site metriklerini daha iyi anlamaları ve sorunlar ortaya çıktığında teşhis aracı olarak kullanmaları amaçlanmaktadır. Yeni API'yi kullanıyorsanız Chrome UX Report (Discussions) Google Grubu'nda geri bildirimlerinizi paylaşabilirsiniz.

Teşekkür

Unsplash'te Dave Herring tarafından çekilen hero resmi