Analytics Ve Script'ler

Bu belge, sitenin izleme ve harici script katmanını anlatır: ziyaretçi sayımı, ısı haritası, reklam pikseli ve chat widget gibi araçlar.

Tüm script’ler tek dosyada tanımlanır (src/config/analytics.ts) ve tek yerden yüklenir (BaseLayout.astro). Sayfa dosyalarına (index.astro, blog vb.) analytics kodu yazılmaz.

Ne İşe Yarar?

Araç	Ne ölçer / yapar
Google Tag Manager (GTM)	Bir konteynerden birden fazla etiketi yönetir (GA4, Ads, vb.)
Google Analytics 4 (GA4)	Sayfa görüntüleme, trafik kaynağı, dönüşümler
Microsoft Clarity	Oturum kaydı, tıklama haritası, scroll davranışı
Meta Pixel	Facebook/Instagram reklam dönüşümleri
customScripts	Hotjar, Crisp, özel embed — standart alanlara sığmayan script’ler

Neden merkezi?

Her sayfada aynı kodu tekrarlamazsınız.
Açıp kapatmak tek satır (enabled, boş ID).
Canlıya geçmeden önce dev ortamında script görmek isteyip istememeyi seçersiniz.

Dosyalar

Dosya	Görev
`src/config/analytics.ts`	ID’ler, aç/kapa, özel script listesi
`src/layouts/BaseLayout.astro`	Koşullu snippet’leri `<head>` ve `<body>`’ye yerleştirir

Başka dosyaya dokunmanız gerekmez. Header, Footer, blog şablonları analytics’ten habersiz kalır.

`analytics.ts` Alanları

export const analytics = {
  enabled: true,
  loadInDev: true,

  googleTagManager: 'GTM-XXXXXXX',
  googleAnalytics4: 'G-XXXXXXXXXX',
  microsoftClarity: '',
  metaPixel: '',

  customScripts: [],
} as const;

`enabled`

true → (diğer koşullar sağlanıyorsa) script’ler yüklenir.
false → hiçbir izleme ve hiçbir customScripts render edilmez.

Staging veya yerel test için en hızlı kapatma yolu.

`loadInDev`

true → npm run dev sırasında da script’ler HTML’e girer (demo / test).
false → script’ler yalnızca production build’de gelir (import.meta.env.PROD).

Canlıya yakın ayar: loadInDev: false — geliştirme sırasında gereksiz istek ve konsol uyarıları olmaz.

ID Alanları (Boş String = Kapalı)

Alan	Örnek değer	Boş (`''`) olunca
`googleTagManager`	`GTM-ABC123`	GTM yüklenmez
`googleAnalytics4`	`G-ABC123`	Doğrudan gtag yüklenmez *
`microsoftClarity`	`abcdefghij`	Clarity yüklenmez
`metaPixel`	`1234567890`	Meta Pixel yüklenmez

* GTM doluysa GA4 doğrudan snippet atlanır. Aynı ziyaretçi iki kez sayılmasın diye. GA4’ü GTM konteyner’ından ekleyin; googleAnalytics4 alanını boş bırakın veya yalnızca GTM kullanmayacaksanız doldurun.

BaseLayout’ta Yükleme Sırası

Script’ler yalnızca BaseLayout üzerinden tüm public sayfalara uygulanır.

<head> içinde (özet sıra):

Tema script’i (flash önleme — analytics değil)
SEO meta (title, canonical, Open Graph)
GTM / GA4 / Clarity / Meta Pixel (koşullu)
customScripts → position: 'head'
OrganizationSchema

<body> içinde:

Açılışta: GTM <noscript> iframe, Meta Pixel <noscript> img
İçerik: Header → main → Footer
Kapanıştan önce: customScripts → position: 'body-end'
En sonda: motion (initMotion)

Sayfa bazlı analytics yok — blog yazısı da ana sayfa da aynı kabuğu kullanır.

Hangi Aracı Nasıl Açarsınız?

Google Tag Manager (Önerilen Tek Giriş)

tagmanager.google.com → konteyner oluşturun.
analytics.ts → googleTagManager: 'GTM-XXXXXXX' (gerçek ID).
googleAnalytics4 → '' bırakın (GTM’den GA4 etiketi ekleyin).
Deploy sonrası View Source’da googletagmanager.com/gtm.js arayın.

GA4 (GTM Kullanmıyorsanız)

Google Analytics → Veri akışı → Ölçüm kimliği G-...
googleTagManager: ''
googleAnalytics4: 'G-...'

İkisini birden doldurmayın (GTM + doğrudan GA4).

Microsoft Clarity

clarity.microsoft.com → proje → Project ID.
microsoftClarity: 'proje-id'

Meta Pixel

Meta Events Manager → Pixel ID.
metaPixel: '1234567890'

`customScripts` — Diğer Kodlar

Standart dört alana sığmayan harici script’ler için:

customScripts: [
  {
    id: 'hotjar',
    position: 'head',
    src: 'https://static.hotjar.com/c/hotjar-XXXX.js',
  },
  {
    id: 'crisp',
    position: 'body-end',
    content: '<script>/* resmi Crisp snippet */</script>',
  },
],

Alan	Açıklama
`id`	Benzersiz isim (debug / `data-analytics-custom` attribute)
`position`	`'head'` veya `'body-end'`
`src`	Harici JS URL — `<script src="..." defer>`
`content`	Ham HTML (genelde platformun verdiği snippet)

src veya content — biri yeterli. İkisi de doluysa src önceliklidir (layout mantığı).

Güvenlik: content yalnızca güvendiğiniz platform snippet’leri için. Config dosyasına rastgele HTML koymak XSS riski taşır.

enabled: false iken customScripts de yüklenmez.

Sık Senaryolar

İstediğin	Ne yap
Tüm izlemeyi kapat	`enabled: false`
Sadece canlıda çalışsın	`loadInDev: false` + production deploy
Sadece GTM	`googleTagManager` dolu, `googleAnalytics4: ''`
Sadece GA4	`googleTagManager: ''`, `googleAnalytics4` dolu
Clarity ekle	`microsoftClarity` dolu
Hotjar ekle	`customScripts` + `position: 'head'`
Bir aracı geçici kapat	İlgili ID’yi `''` yap (dosyayı silmeyin)

Doğrulama

Geliştirme (loadInDev: true):

npm run dev
Herhangi bir sayfa → sağ tık → Sayfa kaynağını görüntüle
GTM- veya gtag / clarity.ms arayın

Production:

npm run build && deploy
Canlı URL’de aynı kontrol
GTM/GA4 panelinde gerçek zamanlı ziyaretçi (ID doğruysa)

Test:

googleTagManager: '' → GTM satırları kaybolmalı
enabled: false → üçüncü parti script kalmamalı

Placeholder GTM-XXXXXXX istek atar ama veri toplamaz; demo yapısı için yeterlidir.

Gizlilik

Analytics kullanıyorsanız:

Gizlilik politikası sayfanızda hangi araçların kullanıldığını belirtin.
AB / TR / UK gibi bölgelerde çerez onayı (CMP) gerekebilir — bu rehber hukuki danışmanlık değildir.
Falcon şablonu çerez banner’ı içermez; GTM üzerinden veya ayrı script ile eklersiniz.

Yapmayın

Her .astro sayfasına ayrı <script> yapıştırmayın.
site.ts veya seo.ts içine analytics ID koymayın — analytics.ts kullanın.
GTM + doğrudan GA4’i aynı anda açmayın.
Production ID’leri commit ederken bilinçli olun (demo placeholder kalabilir).

İlgili Rehberler

Site Layout — BaseLayout yapısı
SEO / Meta — title, canonical (analytics’ten bağımsız)
Production — canlı domain ve checklist

Özet

ID’ler analytics.ts’te; yükleme BaseLayout’ta. Boş string = kapalı. GTM varsa doğrudan GA4 yok. customScripts ile Hotjar vb. Sayfa dosyalarına analytics yazmayın.