Intlayer Analytics Dokümantasyonu

@intlayer/analytics, ziyaretçilerinize gerçekte hangi içeriğin gösterildiğini (hangi sayfanın, hangi yerel ayarda (locale) ve çevrilmiş içeriğin hangi belirli parçasının) size bildiren isteğe bağlı bir yardımcı pakettir, böylece hedef kitlenizi anlayabilir ve içerik üzerinde A/B testleri yürütebilirsiniz.

İçindekiler

Neleri İzler

@intlayer/analytics üç tür anonim olayı toplu olarak işler (batch):

Olaylar bellekte toplanır ve yaklaşık her 20 saniyede bir tek bir toplu istek (batch request) olarak gönderilir — asla her tuş vuruşunda veya oluşturmada (render) değil — bu nedenle analitik, ilk oluşturma süresini asla etkilemez veya her etkileşim başına bir istek eklemez.

İçerikte A/B Testini Nasıl Destekler

Intlayer zaten içerik Varyantları (Variants) (örneğin bir control ve bir black_friday varyantına sahip bir hero-banner sözlüğü) bildirmenize izin verir. @intlayer/analytics bu döngüyü tamamlar:

1. getVariant(experimentKey, variants) her anonim oturumu deterministik olarak bir varyanta atar — oturum kimliğinin ve deney anahtarının (experiment key) saf bir işlevidir (pure function), bu nedenle atama tüm oturum boyunca kararlıdır ve ilk oluşturmadan önce sunucu gidiş-dönüşü (server round-trip) gerektirmez (titreme yok, düzen kayması (layout shift) yok).
2. Her content_exposure olayı gösterilen variant bilgisini taşır.
3. useConversion(), bir hedefi (örneğin "cta_click") o varyanta atfetmenize (attribute) olanak tanır.
4. Gösterge panelindeki deney sonuçları (experiment results) uç noktası, istatistiksel anlamlılık (z-testi) dahil olmak üzere varyant başına dönüşüm oranlarını (conversion rates) karşılaştırır.

Kurulum

@intlayer/analytics eş düzey, isteğe bağlı (peer, optional) bir bağımlılıktır — bir çerçeve (framework) paketi tarafından asla otomatik olarak kurulmaz. intlayer'ın yanına ekleyin:

npm install @intlayer/analytics

Kurmazsanız, her entegrasyon noktası etkisiz bir işlem (no-op) olarak çözülür — aşağıdaki Kurulmadığında sıfır maliyet bölümüne bakın.

Yapılandırma

Analytics, mevcut editor yapılandırma bloğunu yeniden kullanır — doldurulacak ayrı bir analytics yapılandırma şeması yoktur:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  editor: {
    backendURL: "https://back.intlayer.org", // Analytics veri alma uç noktası (ingestion endpoint) olarak da kullanılır
    clientId: "your-client-id", // Analytics proje anahtarı olarak da kullanılır
    clientSecret: "your-client-secret",
  },
};

export default config;

• editor.backendURL — analitik olaylarının gönderildiği temel URL (POST {backendURL}/api/analytics/events).
• editor.clientId — yutulan her olaya atfedilen genel proje anahtarı. Aynı zamanda bir etkinleştirme anahtarı (enable switch) işlevi görür: clientId yapılandırılana kadar analizler tamamen devre dışı bırakılır (ve ölü kod olarak atılır (tree-shaken), aşağıya bakın).

Intlayer'ı kendi başınıza barındırıyorsanız (self-host), analiz otomatik olarak editor.backendURL'yi paylaştığı için kendi örneğinize (instance) işaret eder.

Çerçeve (Framework) Desteği

Analytics, react-intlayer'dan paylaşılan IntlayerProvider'a bağlanmıştır, bu nedenle bugün bu sağlayıcının kullanıldığı her yerde mevcuttur:

Kullanım

Otomatik sağlayıcı (provider) düzeyinde izleme

Kod değişikliği gerekmez. @intlayer/analytics kurulduktan ve editor.clientId yapılandırıldıktan sonra IntlayerProvider otomatik olarak:

• mount edildiğinde (bağlandığında) analiz istemcisini başlatır,
• ilk yüklemede bir page_view kaydeder,
• her yerel ayar değişikliğinde bir page_view kaydeder,
• ~20s boşaltma (flush) döngüsünü başlatır ve unmount / sekme kapatıldığında (tab close) kalan tüm olayları boşaltır (navigator.sendBeacon aracılığıyla, fetch(..., { keepalive: true }) işlevine geri dönerek (fallback)).

Otomatik düğüm (node) düzeyinde izleme

useIntlayer görüntüleme için bir içerik parçasını her çözümlediğinde, yorumlayıcı (interpreter) o tam dictionaryKey + anahtar yolu (key path) + yerel ayar (locale) için bir content_exposure olayı bildirir — yine, hiçbir kod değişikliği gerekmez. Aynı düğümün bir boşaltma penceresi (flush window) içindeki tekrarlanan gösterimleri bir count (sayım) ile tek bir olayda birleştirilir (coalesced), bu nedenle 50 kez yeniden oluşturulan (re-render) bir liste 50 olay göndermez.

A/B testleri için dönüşümleri izleme

Bir oturumun (session) gördüğü varyanta bir hedef atfetmek için useConversion() kullanın:

Bir varyantı istemci tarafında çözümleme (Resolving a variant client-side)

Gizlilik ve Performans

• Tasarım gereği anonim: Oturumlar dönen (rotating) bir id ile tanımlanır; arka uç (backend) yalnızca o kimliğin bir SHA-256 karmasını (hash) saklar — asla ham id'yi ve asla bir IP adresini saklamaz.
• Konum kabadır (coarse): Yalnızca CDN coğrafi konum başlıklarından (geolocation headers) (cf-ipcountry, x-vercel-ip-country, ...) elde edilen bir ülke kodu — hiçbir IP okunmaz veya saklanmaz.
• URL'ler arama parametrelerini varsayılan olarak hariç tutar, bu nedenle sorgu dizeleri (query strings) asla yakalanmaz.
• Örnekleme (Sampling): sampleRate, trafiği yüksek uygulamalarda içerik gösterimi olaylarının yalnızca bir kısmını saklamanıza olanak tanır.
• Toplu İşleme (Batched): Yaklaşık her 20 saniyede bir istek (flushInterval) veya arabellek (buffer) dolarsa daha erken (maxBufferSize) — hiçbir zaman olay başına bir istek değil.

Kurulmadığında sıfır maliyet (Zero-cost when not installed)

@intlayer/analytics, @intlayer/editor ile tamamen aynı isteğe bağlı bağımlılık desenini izler:

• Her entegrasyon noktası, paketi try/catch içine sarılmış dinamik bir import() aracılığıyla yükler — @intlayer/analytics'i hiç kurmayan bir uygulama hiçbir zaman paket boyutu veya çalışma zamanı (runtime) maliyeti ödemez ve hiçbir zaman bir hata görmez;
• editor.clientId yapılandırılmadığında @intlayer/config tarafından otomatik olarak 'false' olarak ayarlanan derleme zamanı (compile-time) ortam değişkeni (INTLAYER_ANALYTICS_ENABLED), paketleyicilerin (bundlers) tüm entegrasyonu ölü kod olarak elemesini (dead-code-eliminate) sağlar;
• Analytics, Intlayer düzenleyicisi (editor)/CMS önizleme (preview) iframe'i içinde devre dışı bırakılır, böylece düzenleyici oturumları (editor sessions) hiçbir zaman gerçek trafik olarak sayılmaz.

Gösterge Paneli (Dashboard): Analytics sayfası

Projeniz olayları topladıktan sonra, Intlayer gösterge paneli (dashboard) içindeki Analytics sayfası (bir proje seçildikten sonra kenar çubuğunda (sidebar) görünür) şunları gösterir:

• Aktif kullanıcılar — seçilen hareketli penceredeki (7 / 30 / 90 gün) benzersiz (distinct) ziyaretçiler.
• Bugünkü kullanıcılar ve son 7 gündeki kullanıcılar.
• Seçili pencere boyunca Sayfa görüntülemeleri (Page views).
• Günlük tekil ziyaretçilerin bir gelişim grafiği (evolution graph).
• Hedef kitlenizi yerel ayar ve ülkeye göre sıralayan Yerel Ayarlar (Locales) ve Konum (Location) döküm sekmeleri.

Arka Uç API Referansı (Backend API reference)

Tüm okuma uç noktaları (read endpoints) kimlik doğrulama gerektirir; veri alımı (ingestion) geneldir (public) ve gövdedeki clientId tarafından ilişkilendirilir (attributed).

Bunları CMS SDK ile programatik olarak da çağırabilirsiniz:

import { createIntlayerCMS } from "@intlayer/api";import { analyticsEndpoint } from "@intlayer/api/analytics";const cms = createIntlayerCMS();const { data: audience } = await analyticsEndpoint(cms).getAudience(30);

Faydalı bağlantılar (Useful links)

• Dinamik Sözlükler - Koleksiyonlar ve Varyantlar (Dynamic Dictionaries)
• Intlayer CMS - CMS SDK
• Intlayer Görsel Düzenleyici (Visual Editor)
• Yapılandırma Referansı (Configuration Reference)
• Kendi Başına Barındırma (Self-Hosting) Kılavuzu