Google, arama sıralamalarında Core Web Vitals verilerine ağırlık verdiğini açıkladığından bu yana birçok geliştirici PageSpeed Insights'ı açar, skoru okur ve kapatır. Lab verisi bir şey söyler; gerçek kullanıcıların tarayıcıda ne yaşadığını söylemez. Sahadan veri toplamak için web-vitals kütüphanesi tam bu noktada iş görür.

Kütüphane, Google tarafından geliştirilen ve npm üzerinden dağıtılan küçük bir JavaScript paketidir. LCP (Largest Contentful Paint), CLS (Cumulative Layout Shift) ve INP (Interaction to Next Paint) değerlerini, Chrome'un PerformanceObserver API'si aracılığıyla gerçek oturumlarda ölçer. Ölçüm tamamlandığında sizi bir callback ile bilgilendirir; veriyle ne yapacağınızı siz belirlersiniz. En yaygın tercih, bu veriyi GA4'e özel bir event olarak göndermektir.

Kurulum yüzeysel olarak kısadır: yükle, ölç, gönder. Ama birkaç ayrıntıyı gözden kaçırmak veriyi anlamsız ya da gürültülü hale getirebilir. Attribution, örnekleme ve boyut kaydı bu üç noktada kırılır.

web-vitals Kütüphanesi Nasıl Çalışır?

Kütüphane, tarayıcının sunduğu ham performans API'lerini sarmalayan bir katmandır. Her metrik için ayrı bir fonksiyon dışarı açılır: onLCP, onCLS, onINP. Bu fonksiyonları çağırdığınızda, kütüphane arka planda bir PerformanceObserver dinleyicisi başlatır ve metrik için doğru anı bekler.

LCP için doğru an, kullanıcının sayfayla ilk etkileşimi veya sayfa gizlenmeden önceki son andır. CLS birden fazla düzen kaymasını (layout shift) biriktirir ve sayfa gizlendiğinde toplam skoru raporlar. INP tüm etkileşimleri izler, en yavaş olanı seçer ve kullanıcı sayfadan ayrılmadan önce son değeri callback'e iletir.

Veri yalnızca Chromium tabanlı tarayıcılarda toplanabilir; Safari ve Firefox bu API'leri desteklemez. Gerçek kullanıcı verisinin bir bölümü dolayısıyla eksik kalacaktır. Bunun bir ölçme hatası değil, tarayıcı desteğinin doğal bir kısıtı olduğunu raporları okurken göz önünde tutmak gerekir.

Paket boyutu yaklaşık 2-3 KB sıkıştırılmış olarak gelir. Üretim paketine eklemek yükleme süresine anlamlı bir yük bindirmez.

GA4'e Custom Event Göndermek: Temel Kurulum

Kurulum iki adımdan oluşur: paketi yüklemek ve her metrik için bir callback tanımlamak. Callback içinde gtag('event', ...) ile GA4'e bir olay iletirsiniz.

import { onLCP, onCLS, onINP } from 'web-vitals';

function sendToGA4({ name, value, rating, id }) {
  gtag('event', name, {
    value: Math.round(name === 'CLS' ? value * 1000 : value),
    metric_id: id,
    metric_rating: rating,
    non_interaction: true,
  });
}

onLCP(sendToGA4);
onCLS(sendToGA4);
onINP(sendToGA4);

name alanı doğrudan event adı olarak kullanılır; GA4 arayüzünde LCP, CLS, INP adında üç özel event görürsünüz. value değeri milisaniye cinsinden gelir, CLS için bu değer 0-1 aralığında bir ondalık sayıdır ve tam sayı olarak saklamak için 1000 ile çarpmak yaygın bir tercihtir. metric_id her oturum için benzersiz bir kimlik taşır, aynı oturumdan gelen birden fazla kaydı birleştirmek ya da tekilleştirmek istediğinizde bu alana ihtiyaç duyarsınız. rating alanı good, needs-improvement veya poor değerlerinden birini alır ve segmentasyon için kullanışlıdır.

non_interaction: true eklemek şarttır. Aksi halde GA4 bu event'i kullanıcı etkileşimi olarak sayar ve hemen çıkma oranı gibi davranış metriklerini bozar.

Ölçümün Doğruluğunu Etkileyen Ayrıntılar

Kütüphaneyi projeye ekleyip callback yazdınız; iş bitti mi? Birkaç köşe nokta veriyi yanlış okutabilir.

İlk mesele, callback'in çağrılma zamanlamasıdır. LCP callback'i, kullanıcı sayfayla etkileşime geçene kadar tetiklenmez. Kullanıcı sayfayı açıp hemen kapatan, hiç etkileşim kurmadan giderse bu oturum için LCP verisi toplanmaz; düşük etkileşimli sayfalarda LCP örnek sayısı gerçek trafikten az çıkar ve yüksek hemen çıkma oranı olan sayfalar az veriyle az sorunluymuş gibi görünür.

Yanıltıcı veri buradan gelir.

İkinci mesele, sayfa önbelleklemesidir (bfcache - back/forward cache). Kullanıcı geri tuşuyla bir sayfaya döndüğünde, sayfa genellikle bellekten yüklenir ve LCP yeniden hesaplanır. reportAllChanges seçeneğini açarsanız bu ölçümleri de yakalayabilirsiniz; ancak raporlarda yinelenen kayıtlar çıkar ve metric_id ile tekilleştirme önem kazanır.

Üçüncü mesele CLS için özellikle geçerlidir: sayfanın tamamı yüklenip düzen otururken birden fazla callback tetiklenebilir. reportAllChanges kapalıyken yalnızca son değer gelir, açıkken her güncelleme ayrı bir event üretir. Düzen geçmişini analiz etmek istiyorsanız reportAllChanges: true tercih edilir; veri hacmini sınırlamak istiyorsanız kapalı bırakın.

// Tüm CLS güncellemelerini yakalamak için:
onCLS(sendToGA4, { reportAllChanges: true });

Veri Hacmini Yönetmek: Örnekleme ve Filtreleme

Tüm kullanıcılardan veri toplamak her zaman doğru değildir. Yüksek trafikli sayfalarda GA4'e akan olay sayısı ücretsiz kotayı zorlayabilir ve analizleri yavaşlatabilir. Örnekleme burada devreye girer.

Basit bir örnekleme mantığı şöyle yazılabilir:

function sendToGA4(metric) {
  if (Math.random() > 0.1) return; // yüzde onluk örnekleme
  gtag('event', metric.name, {
    value: Math.round(metric.name === 'CLS' ? metric.value * 1000 : metric.value),
    metric_id: metric.id,
    metric_rating: metric.rating,
    non_interaction: true,
  });
}

Örneklemeyi kullanıcı düzeyinde mi yoksa sayfa yüklemesi düzeyinde mi uygulayacağınız analiz hedeflerinize göre değişir. Kullanıcı düzeyinde örnekleme için rastgele sayıyı sessionStorage'a yazarak oturum boyunca sabit tutabilirsiniz; sayfa yüklemesi düzeyinde örnekleme, yukarıdaki gibi her yüklemede yeni bir rastgele sayı üretir.

Filtreleme tarafında, kendi geliştirici oturumlarınızı dışarıda bırakmak veriyi temizler. GA4'te debug_mode parametresini üretim ortamında kapalı, yerel ortamda açık tutabilirsiniz; bu sayede geliştirme sırasında üretilen ölçümler raporu kirletmez.

GA4 Raporunda Web Vitals Verisi Nasıl Okunur?

Olaylar GA4'e akmaya başlasa da arayüzde birkaç yapılandırma adımı olmadan analiz yapılamaz. GA4, custom event parametrelerini otomatik olarak boyut (dimension) veya metrik olarak tanımaz; bunları manuel olarak kaydetmek gerekir.

Admin > Custom Definitions bölümüne gidin. Buradan metric_rating için "Custom Dimension" (kapsam: event), metric_id için yine "Custom Dimension" ve sayısal değer için "Custom Metric" tanımı oluşturun. Tanımlar kaydedildikten sonra Explore (Keşfet) raporlarında bu alanları kullanabilirsiniz.

Pratik bir analiz akışı şöyle kurulabilir: LCP event'ini seçin, boyut olarak sayfa yolunu (page_path) ekleyin, metrik olarak value alanının ortalamasını alın. GA4 doğrudan medyan veya yüzdelik dilim hesaplamaz; doğruluğu yüksek analiz için verileri BigQuery'ye aktararak 75. yüzdelik dilim üzerinden sorgulamak daha sağlıklı bir yapıdır. Google'ın CrUX'ta kullandığı eşik değer 75. yüzdelik dilimdir ve GA4 Explore bu hesabı yerleşik olarak sunmaz.

Günlük oturum sayısının birkaç yüzün altında kaldığı sayfalarda, küçük örnek boyutundan kaynaklanan salınımlar yanıltıcı çıkabilir. Bu sayfalarda verileri haftalık birleştirerek okumak daha güvenilir sonuç verir.

Hangi Sayfalar Önce İzlenmeli?

Her sayfaya eşit önem atamak kaynakları dağıtır. Dönüşüm hunisindeki sayfalar - ana sayfa, ürün sayfaları, ödeme akışı - hem kullanıcı etkisi hem de iş etkisi açısından önceliklidir. Bu sayfalarda LCP kötüyse kullanıcı, sayfanın yüklendiğini beklerken ödeme adımında beklemek zorunda kalır; CLS kötüyse düzenin kaymasıyla yanlış bir alana dokunabilir.

Blog sayfaları ve arşiv listeleri çoğu durumda daha az kritiktir; ama bu sayfalar önemli organik trafik çekiyorsa sıralama üzerindeki etkileri nedeniyle izlenmeye değerdir. Kararı trafik verisi ve dönüşüm hedefleri belirler.

İzlemeden çıkarmak mantıklı olan sayfalar da vardır: admin panelleri, giriş ekranları, oturum gerektiren alanlar. Bu sayfalarda toplanan veri ne Google'ın değerlendirmesiyle örtüşür ne de kullanıcı deneyimi kararlarına anlamlı bir katkı sağlar. Bunları URL filtreleriyle GA4 property'sinden dışarıda tutmak veriyi daha net tutar.

Sık Yapılan Hatalar ve Temiz Yapı

Eksik custom dimension tanımı en yaygın sorundur. Kütüphaneyi kurdunuz, veriler GA4'e akıyor; ama Explore'da metric_rating boyutunu göremiyorsunuz çünkü tanımlanmamış. Veri gelir, analiz edilemez hale kalır.

İkinci yaygın hata, birden fazla kez çağrılan callback'tir. onLCP'yi birden fazla yerde çağırırsanız ya da sayfa her render edildiğinde yeniden çalışan bir bileşene koyarsanız, aynı oturum için birden fazla event gönderilir ve medyan hesaplamaları bozulur. Callback'leri uygulama başlatma aşamasında bir kez, modül seviyesinde çağırmak bu riski ortadan kaldırır.

Üçüncü hata, değerleri yuvarlamadan GA4'e göndermektir. GA4 tam sayıları daha iyi saklar ve raporlar. LCP için milisaniyeyi Math.round() ile tamsayıya, CLS için ondalık değeri 1000 ile çarpıp yuvarlayarak göndermek standart yaklaşımdır. Son olarak, metric_id alanını göz ardı etmek tekilleştirme imkânını ortadan kaldırır; aynı oturum için birden fazla CLS güncellemesi gelirse hangisinin en son değer olduğunu ayırt etmek güçleşir.

Web vitals izlemesini doğru kurmak, PageSpeed skorunu yükseltmekten ayrı bir iştir. Skor, lab ortamında tek bir simülasyonu yansıtır; sahadan gelen veri ise farklı cihazlar, bağlantı hızları ve tarayıcı davranışlarının gerçek karışımını gösterir. İkisinin çeliştiği durumlarda saha verisi daha güvenilir bir rehberdir.

Kurulum tamamlandıktan sonra ilk birkaç günün verisine hemen karar verme baskısıyla bakmamak yerinde olur; örnek sayısı yeterince büyüdükçe hangi sayfanın hangi metrikte sorunlu olduğu netleşir ve iyileştirme sırası kendiliğinden belirir.