CrUX API ile Rakip Sitenin Performansını Nasıl İzlersiniz?

API anahtarı almak ve ilk isteği hazırlamak

CrUX API, Google'ın diğer API'leriyle aynı altyapıyı kullanır. Google Cloud Console üzerinden bir proje oluşturup "Chrome UX Report API"yi etkinleştirmeniz, ardından bir API anahtarı üretmeniz yeterlidir. Ücretsiz kota dakikada 150 istek olarak belirlenmiştir; bu miktar, düzenli çalışan bir izleme betiği için fazlasıyla yeterlidir. Kota aşılırsa API 429 döndürür ve isteği kısa bir beklemeden sonra yeniden denemeniz gerekir.

İlk isteği komut satırından şöyle çalıştırabilirsiniz:

curl -X POST \
  "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "https://example.com"
  }'

Yanıt, her metrik için histogram verileri ve yüzdelik dilim değerleri içerir. p75 alanı 75. yüzdelik dilim değerini verir. Google'ın "geçti/kaldı" kararını bu değer üzerinden aldığını bilmek önemlidir; histogram dağılımı ek bağlam sağlasa da asıl eşiği p75 belirler.

Origin yerine belirli bir URL sorgulamak istediğinizde istek gövdesini şöyle değiştirirsiniz:

{
  "url": "https://example.com/urun/spor-ayakkabi"
}

Belirli bir form faktörü için filtre de ekleyebilirsiniz:

{
  "url": "https://example.com/urun/spor-ayakkabi",
  "formFactor": "PHONE"
}

PHONE, DESKTOP ve TABLET değerleri geçerlidir. Form faktörü belirtmezseniz API tüm cihaz tiplerini birleştirerek yanıt döndürür. Mobil ve masaüstü trafiğinin performansı ciddi biçimde farklılaşabildiğinden, rakip karşılaştırmasında her iki form faktörünü ayrı ayrı sorgulamak tablonuza daha net bir görünüm kazandırır.

Origin sorgusu ile URL sorgusu arasındaki fark

Origin sorgusu, bir domain'in tamamını tek bir veri noktasında özetler. Rakip sitenin genel durumunu anlamak için başlangıç noktası olarak kullanışlıdır; ancak bir sitenin ürün sayfaları yavaş, blog sayfaları hızlıysa bu iki değer tek sayıda kaybolur. Origin verisi sitenin ortalaması olduğundan, belirli bir rekabet alanındaki gerçek durumu yansıtmayabilir.

URL sorgusu ise belirli bir sayfanın gerçek performansını gösterir. Rakibinizin sizinle doğrudan rekabet ettiği sayfalar için - aynı ürün kategorisi, aynı anahtar kelime grubu - URL düzeyinde sorgu çok daha anlamlıdır. Rakibinizin kategori sayfası hızlıyken ana sayfası yavaşsa, origin sorgusuyla bu ayrımı göremezsiniz.

Bir kısıt var. URL düzeyinde verinin oluşması için o sayfanın Chrome kullanıcılarından yeterli trafik alması gerekir. Aylık birkaç bin ziyaret alan niş sayfalar çoğunlukla veri döndürmez; bu durumda origin verisi tek seçenek olur.

Rakibin ana sayfası, kategori sayfaları veya en çok trafik alan landing page'leri için URL sorgusu deneyin. Yanıt NOT_FOUND içeriyorsa origin sorgusuyla devam edin ve bu ayrımı benchmark tablonuzda kayıt altına alın. "Origin verisi" ile "URL verisi" aynı sütuna düşürülmemelidir; ikisi farklı güven düzeyine sahip ölçümlerdir.

LCP, CLS ve INP verilerini doğru okumak

API yanıtı Core Web Vitals metriklerini hem histogram hem de yüzdelik dilim değerleriyle sunar. Histogram, kullanıcıların kaçının hangi aralıkta deneyim yaşadığını gösterir; ancak karşılaştırma tablosu için p75 değerleri çoğu zaman daha pratik bilgi verir. Histogramdaki "iyi" diliminin yüzdesine bakarak sitenin ne kadarının eşiği geçtiğini de görebilirsiniz; bu oran, p75 değerinin tek başına vermediği bir dağılım bilgisi taşır.

Eşikler bellidir. LCP için 2500 ms altı iyi, 2500-4000 ms arası iyileştirme gerekiyor, 4000 ms üzeri kötü. CLS için 0.1 altı iyi, 0.1-0.25 arası iyileştirme gerekiyor, 0.25 üzeri kötü. INP için 200 ms altı iyi, 200-500 ms arası iyileştirme gerekiyor, 500 ms üzeri kötü.

API yanıtından bu değerleri çıkarmak için Python ile basit bir ayrıştırıcı yazabilirsiniz:

import requests

API_KEY = "YOUR_API_KEY"
ENDPOINT = "https://chromeuxreport.googleapis.com/v1/records:queryRecord"

def get_crux_data(url, form_factor="PHONE"):
    payload = {"url": url, "formFactor": form_factor}
    response = requests.post(
        f"{ENDPOINT}?key={API_KEY}",
        json=payload
    )
    return response.json()

def extract_p75(data, metric):
    try:
        return data["record"]["metrics"][metric]["percentiles"]["p75"]
    except KeyError:
        return None

site = "https://example.com/kategori/ayakkabi"
data = get_crux_data(site)

lcp = extract_p75(data, "largest_contentful_paint")
cls = extract_p75(data, "cumulative_layout_shift")
inp = extract_p75(data, "interaction_to_next_paint")

print(f"LCP: {lcp} ms, CLS: {cls}, INP: {inp} ms")

CLS değeri milisaniye değil ham sayı olarak döner (örneğin 0.08), diğer metrikler milisaniye cinsinden gelir. Tablonuza eklerken bu farkı kayıt altına almanız ileride karışıklığı önler. Aynı durum FCP (First Contentful Paint) için de geçerlidir; API FCP verisini de döndürür, ancak FCP Core Web Vitals eşikleriyle değil ayrı eşiklerle değerlendirilir.

Rakip URL'leri için benchmark tablosu oluşturmak

Tablo oluşturmanın ilk adımı izlenecek URL listesini derlemektir. Kendi sitenizin hangi sayfaları için rakip analizi yapmak istediğinizi belirleyin, ardından rakip sitelerde karşılık gelen sayfaları tespit edin. Bir e-ticaret sitesiyseniz kategori sayfaları ve ana ürün listeleri; bir haber sitesiyseniz ana sayfa ve popüler içerik kategorileri iyi başlangıç noktalarıdır.

Tablo yapısı şöyle kurulabilir: her satır bir URL, sütunlar ise LCP p75, CLS p75, INP p75, veri türü (origin/URL), form faktörü ve sorgu tarihi. Veri türü sütununu özellikle tutun; origin verisiyle URL verisi aynı güven düzeyinde yorumlanamaz. Bir rakibin belirli URL'i için NOT_FOUND aldıysanız, o hücreye "veri yok" yazmak yerine "origin verisi kullanıldı" yazın ve origin p75'i oraya taşıyın.

Python ile birden fazla rakip URL'ini döngüyle sorgulamak mümkündür:

import time

urls = [
    {"label": "Kendi siteniz - kategori", "url": "https://sizinsite.com/kategori/ayakkabi"},
    {"label": "Rakip A - kategori",       "url": "https://rakipa.com/kategori/ayakkabi"},
    {"label": "Rakip B - kategori",       "url": "https://rakipb.com/kategori/ayakkabi"},
]

results = []
for item in urls:
    data = get_crux_data(item["url"], form_factor="PHONE")
    results.append({
        "label": item["label"],
        "lcp":   extract_p75(data, "largest_contentful_paint"),
        "cls":   extract_p75(data, "cumulative_layout_shift"),
        "inp":   extract_p75(data, "interaction_to_next_paint"),
    })
    time.sleep(0.5)

for r in results:
    print(r)

time.sleep zorunlu değildir, ancak arka arkaya çok sayıda istek geldiğinde API zaman zaman gecikmeli yanıt verir. Günlük 150 istek kotasını takip edin; test aşamasında bu kotayı beklenmedik biçimde tüketmek kolaydır.

Düzenli izleme için betik zamanlama ve veri saklama

Anlık bir sorgu size bugünün tablosunu verir. Rakip sitenin LCP değerinin geçen ay 3200 ms'den bu ay 2100 ms'e düştüğünü ancak aylık kayıt tutarsanız görebilirsiniz. CrUX verisi gerçek zamanlı değildir; Google bunu 28 günlük kayan pencere üzerinden günceller, bu nedenle haftalık sorgu yeterlidir ve gerçekçi bir değişim takibine olanak tanır.

Haftalık çalışacak bir zamanlayıcı için birkaç seçenek vardır: Linux/macOS'ta cron, Windows'ta Task Scheduler, GitHub Actions üzerinde ücretsiz zamanlı iş. Verilerinizi CSV veya SQLite'a yazmak sorgu başına tutulacak en sade yapıdır; karmaşık bir veritabanı kurmaya gerek yoktur.

# .github/workflows/crux-weekly.yml
name: CrUX Weekly Benchmark
on:
  schedule:
    - cron: "0 6 * * 1"   # her Pazartesi 06:00 UTC
jobs:
  benchmark:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Python kurulumu
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Bağımlılıkları yükle
        run: pip install requests
      - name: Benchmark çalıştır
        env:
          CRUX_API_KEY: ${{ secrets.CRUX_API_KEY }}
        run: python benchmark.py
      - name: Sonuçları kaydet
        uses: actions/upload-artifact@v4
        with:
          name: crux-results
          path: results/

API anahtarını deponuzda düz metin olarak saklamayın; GitHub Secrets veya ortam değişkeni kullanın. Betik çıktısını her çalışmada aynı CSV dosyasına satır ekleyerek biriktirebilirsiniz; böylece birkaç ay sonra geri bakıp eğilimi görebilirsiniz. Rakip site altyapısını değiştirdiğinde veya CDN geçişi yaptığında bu haftalık kayıtlar neyin ne zaman değiştiğini gösteren tek kaynağınız olur.

Sonuçları yorumlamak ve veri dönmeyen URL'lerle başa çıkmak

İki sayı arasındaki fark her zaman eylem gerektirmez. CrUX verisi 28 günlük kayan penceredir; kısa süreli değişiklikler veya sezonluk trafik dalgalanmaları anlık ölçümü etkiler. Rakibinizin LCP'si sizden 200 ms daha kısa görünüyorsa bu fark ölçüm gürültüsü içinde kaybolabilir. Tutarlı, üç haftadan uzun süre devam eden bir fark daha güvenilir bir sinyaldir.

Kategori farkına bakın. Rakibinizin LCP değeri "iyi" eşiğinin altında (2500 ms altı) kalırken sizinki "iyileştirme gerekiyor" bandında (2500-4000 ms arası) bekliyorsa, bu sayısal farktan daha ağır bir bulgudur; Google sizin sayfanızı bu eşiğe göre ayrı değerlendirebilir. Aynı kategoride buluşmak, milisaniye yarışından önce gelir.

INP yorumlarken dikkatli olun. INP tüm etkileşimlerin en yavaşını değil, 98. yüzdelik dilim etkileşimi temsil eder. Rakibinizin INP p75 değeri sizden düşükse etkileşimlerin büyük çoğunluğu daha hızlı yanıt veriyor demektir; bu, JavaScript yükü veya olay işleyici maliyetinin sizden daha düşük olduğunu gösterir. CLS karşılaştırması en sezgiseldir. Sıfıra yakın değerler (0.05 altı) gerçek anlamda sağlam bir düzen stabilitesini temsil eder; rakibinizin 0.02 değeri varken sizin 0.18'iniz varsa görsel stabilitede ciddi bir açık söz konusudur.

Bazı rakip URL'leri veri döndürmez. Bunun üç olası nedeni vardır: ilgili sayfanın yeterli Chrome trafiği yoktur, URL kısa süre önce değişmiştir ve eski adres hâlâ sorgulanmaktadır ya da o sayfa giriş gerektirdiğinden Chrome kullanıcılarının yalnızca küçük bir kısmı ulaşmaktadır. Bu durumda önce origin sorgusuyla deneyin. Origin verisi makul bir vekil değer sağlar; ancak o satırı tablonuzda "origin (yedek)" olarak işaretleyin. Alternatif olarak, rakibin aynı amaca hizmet eden farklı bir sayfasını deneyin; bu vekil sayfa-düzeyi karşılaştırmayı tam karşılamaz, yine de hiç veri olmamaktan daha bilgilendiricidir.