Nuxt Server Tracking

🚀 Server-side GA4 ve Meta Pixel tracking paketi for Nuxt 3

Bu paket, Google Analytics 4 (GA4) ve Meta Pixel event'lerini client-side JavaScript yerine server-side API üzerinden gönderir. Bu sayede:

• ✅ Ad blocker'lardan etkilenmez - Server-side tracking engellenmez
• ✅ Daha güvenilir veri - Client-side script'ler yüklenmese bile tracking çalışır
• ✅ Daha iyi performans - Client-side'da daha az JavaScript
• ✅ Privacy-friendly - Hassas verileri server'da işleyebilirsiniz
• ✅ E-commerce ready - Tüm e-commerce event'leri desteklenir

Kurulum

npm install nuxt-server-tracking

Konfigürasyon

nuxt.config.ts dosyanızda modülü ekleyin:

export default defineNuxtConfig({
  modules: ['nuxt-server-tracking'],
  
  serverTracking: {
    // GA4 ayarları
    ga4: {
      enabled: true,
      measurementId: 'G-XXXXXXXXXX',
      apiSecret: 'your-api-secret',
      debug: false // development için true yapın
    },
    
    // Meta Pixel ayarları
    meta: {
      enabled: true,
      pixelId: 'your-pixel-id',
      accessToken: 'your-access-token',
      testEventCode: 'TEST12345', // test etmek için (opsiyonel)
      debug: false
    },
    
    // Otomatik sayfa görüntüleme tracking
    autoPageView: true,
    
    // E-commerce ayarları
    ecommerce: {
      enabled: true,
      currency: 'USD' // Varsayılan para birimi
    }
  }
})

GA4 API Secret Nasıl Alınır?

1. Google Analytics 4 özelliğinize gidin
2. Admin > Data Streams > Web stream'inizi seçin
3. "Measurement Protocol API secrets" bölümüne gidin
4. "Create" butonuna tıklayın
5. Bir isim verin ve secret'ınızı kopyalayın

Meta Access Token Nasıl Alınır?

1. Meta Events Manager'a gidin
2. Pixel'inizi seçin
3. Settings > Conversions API sekmesine gidin
4. "Generate access token" butonuna tıklayın
5. Token'ı kopyalayın

Kullanım

1. Otomatik Page View Tracking

autoPageView: true ayarıyla tüm sayfa görüntülemeleri otomatik olarak track edilir. Hiçbir kod yazmanıza gerek yok! 🎉

2. Manuel Tracking (Composable)

Component'lerinizde useTracking() composable'ını kullanın:

<template>
  <div>
    <button @click="handleAddToCart">Sepete Ekle</button>
    <button @click="handlePurchase">Satın Al</button>
  </div>
</template>

<script setup>
const tracking = useTracking()

// Ürün görüntüleme
const product = {
  id: 'PROD123',
  name: 'Awesome T-Shirt',
  category: 'Clothing',
  price: 29.99,
  currency: 'USD'
}

onMounted(() => {
  tracking.viewItem(product)
})

// Sepete ekleme
const handleAddToCart = () => {
  tracking.addToCart(product, 1) // quantity = 1
}

// Satın alma
const handlePurchase = () => {
  tracking.purchase({
    id: 'ORDER123',
    total: 29.99,
    tax: 2.50,
    shipping: 5.00,
    currency: 'USD',
    items: [{
      id: 'PROD123',
      name: 'Awesome T-Shirt',
      category: 'Clothing',
      price: 29.99,
      quantity: 1
    }]
  })
}
</script>

3. Tüm E-commerce Event'leri

const tracking = useTracking()

// 1. Ürün görüntüleme
tracking.viewItem({
  id: 'PROD123',
  name: 'Product Name',
  category: 'Category',
  price: 99.99,
  currency: 'USD'
})

// 2. Sepete ekleme
tracking.addToCart(product, quantity)

// 3. Sepetten çıkarma
tracking.removeFromCart(product, quantity)

// 4. Checkout başlatma
tracking.beginCheckout([item1, item2], totalValue)

// 5. Ödeme bilgisi ekleme
tracking.addPaymentInfo([item1, item2], totalValue, 'credit_card')

// 6. Satın alma tamamlama
tracking.purchase({
  id: 'ORDER123',
  total: 199.99,
  tax: 15.00,
  shipping: 10.00,
  coupon: 'SUMMER2024',
  currency: 'USD',
  items: [...]
})

// 7. Arama
tracking.search('blue t-shirt', searchResults)

// 8. Lead (Form gönderimi)
tracking.lead('contact-form', 0)

// 9. Kayıt tamamlama
tracking.completeRegistration('email')

// 10. Custom event
tracking.custom('button_click', {
  button_name: 'cta_button',
  page: 'homepage'
})

4. API Endpoint ile Manuel Kullanım

İsterseniz doğrudan API endpoint'ini de kullanabilirsiniz:

// Client-side
await $fetch('/api/_tracking', {
  method: 'POST',
  body: {
    eventName: 'add_to_cart',
    params: {
      currency: 'USD',
      value: 29.99,
      items: [{
        item_id: 'PROD123',
        item_name: 'Product Name',
        price: 29.99,
        quantity: 1
      }]
    }
  }
})

Event Mapping

Paket, GA4 ve Meta event isimlerini otomatik olarak eşleştirir:

| Client Event | GA4 Event | Meta Event | |-------------|-----------|------------| | view_item | view_item | ViewContent | | add_to_cart | add_to_cart | AddToCart | | begin_checkout | begin_checkout | InitiateCheckout | | add_payment_info | add_payment_info | AddPaymentInfo | | purchase | purchase | Purchase | | search | search | Search | | lead | generate_lead | Lead | | complete_registration | sign_up | CompleteRegistration |

Debug Mode

Development sırasında debug mode'u aktif edin:

serverTracking: {
  ga4: {
    debug: true // GA4 debug endpoint kullanır
  },
  meta: {
    debug: true, // Console'a yanıtları loglar
    testEventCode: 'TEST12345' // Meta Test Events kullanır
  }
}

Debug mode aktifken:

• GA4: https://www.google-analytics.com/debug/mp/collect kullanır
• Meta: Test event olarak işaretlenir ve Meta Event Manager'da görülebilir

User Data (Privacy-Safe)

Meta Conversions API için kullanıcı verilerini gönderebilirsiniz (hepsi SHA256 hash'li):

tracking.purchase({
  id: 'ORDER123',
  total: 99.99,
  items: [...],
  userData: {
    email: '[email protected]',
    phone: '+1234567890',
    firstName: 'John',
    lastName: 'Doe',
    city: 'New York',
    state: 'NY',
    zip: '10001',
    country: 'US'
  }
})

⚠️ Not: Tüm user data otomatik olarak SHA256 hash'lenerek gönderilir.

Cookie-Based Tracking

Paket otomatik olarak şu cookie'leri algılar:

• _ga - GA4 Client ID
• _fbp - Meta Pixel ID
• _fbc - Meta Click ID

Proje Yapısı

nuxt-server-tracking/
├── src/
│   ├── module.js                          # Ana modül
│   └── runtime/
│       ├── composables/
│       │   └── useTracking.js             # Client composable
│       └── server/
│           ├── api/
│           │   └── track.post.js          # API endpoint
│           ├── middleware/
│           │   └── tracking.js            # Auto page view
│           └── utils/
│               ├── ga4.js                 # GA4 client
│               └── meta.js                # Meta client
└── package.json

Özellikler

✅ GA4 Measurement Protocol - Resmi API kullanır ✅ Meta Conversions API - Server-side event tracking ✅ Auto Page Views - Otomatik sayfa görüntüleme ✅ E-commerce Events - Tüm e-commerce event'leri ✅ Custom Events - İstediğiniz custom event'leri gönderin ✅ Privacy-Safe - SHA256 hash ile kullanıcı verileri ✅ Cookie Support - Client ID ve Pixel ID tracking ✅ Debug Mode - Kolay test ve debug ✅ TypeScript - Tip desteği (yakında)

Lisans

MIT

Katkıda Bulunma

Pull request'ler kabul edilir! Büyük değişiklikler için önce issue açın.

Destek

Sorular veya sorunlar için GitHub Issues kullanın.

Not: Bu paket üretim kullanımı için hazırdır ancak kendi test ortamınızda test etmenizi öneririz.