Flux Analytics Flutter SDK 🚀

Flux Analytics, modern mobil uygulamalar için uçtan uca veri analitiği, kullanıcı davranışı takibi ve performans ölçümleme çözümüdür. KoçSistem tarafından geliştirilen bu SDK, uygulamanızın kalbindeki verileri anlamlandırmanıza yardımcı olur.

📋 İçindekiler

Başlangıç
Kullanıcı Tanımlama
Event Takibi
Gelişmiş Metrik Analizi (Pro)
Ekran Analitiği
Hata ve Performans
En İyi Uygulamalar

📦 Kurulum

pubspec.yaml dosyanıza aşağıdaki satırı ekleyin:

dependencies:
  flux_analytics_sdk: ^0.1.27

Terminalde paketi indirin:

flutter pub get

🚀 Başlangıç

SDK'yı uygulamanızın giriş noktasında (main.dart) tek bir kez ilklendirmeniz yeterlidir.

import 'package:flux_analytics_sdk/flux_analytics_sdk.dart';

void main() async {
  // Flutter binding ilklendirildiğinden emin olun
  WidgetsFlutterBinding.ensureInitialized();

  await Flux.init(
    appId: '93a6e925-04ee-4e5a-9ae0-bc59592f87c3', // Uygulama ID'niz
    firmId: '93a6e925-04ee-4e5a-9ae0-bc59592f87c3', // Firma ID'niz
    debug: true, // Geliştirme modunda konsola log basar
    logLevel: FluxLogLevel.critical, // NONE, CRITICAL (hatalar), VERBOSE (tümü)
  );

  runApp(MyApp());
}

👤 Kullanıcı Tanımlama

Kullanıcıyı sistemde tekil bir ID ile takip etmek analitiğin temelidir.

// Login anında kullanıcıyı işaretleyin
Flux.identify('user_9501');

// Kullanıcıya ait kalıcı etiketler ekleyin (Segmentasyon için)
Flux.setUserProperty('segment', 'premium');
Flux.setUserProperty('last_location', 'Istanbul');

📊 Event Takibi

Ham Eventler (Track)

Kullanıcının yaptığı bir eylemi takip etmek için:

Flux.track('add_to_cart', {
  'category': 'Electronics',
  'item_id': 'iphone_15',
  'source': 'search_results'
});

⏱️ Gelişmiş Metrik Analizi (PRO)

trackMetric özelliği, verilerinizi sadece log olarak değil, dashboard üzerinde VIP Metrik olarak görselleştirmenizi sağlar.

Senaryo 1: API Gecikme Analizi (Average Mode)

Bir isteğin ne kadar sürdüğünü ve ortalamasını dashboard'da mor kartlarda görmek için:

Flux.trackMetric(
  eventName: 'ai_response_time',
  value: stopwatch.elapsedMilliseconds,
  typeLabel: 'Yapay Zeka Yanıt Hızı',
  unit: 'ms',
  mode: 'avg', // Ortalama hesaplar
  icon: 'latency',
  metadata: {
    'model': 'gpt-4o',
    'status': 'success'
  }
);

Senaryo 2: Kategorik Dağılım (Distribution Mode)

Hangi karakterin daha çok seçildiğini veya hangi seviyenin daha çok oynandığını görmek için:

Flux.trackMetric(
  eventName: 'character_selection',
  value: 'Warrior', // Seçilen değer
  typeLabel: 'Karakter Dağılımı',
  mode: 'dist', // Otomatik segmentasyon ve yüzdelik grafiği oluşturur
  icon: 'person'
);

Senaryo 3: Toplam Skor/Kazanç (Sum Mode)

Uygulama içinde kazanılan toplam puanları veya harcanan kredileri toplamak için:

Flux.trackMetric(
  eventName: 'coins_spent',
  value: 50,
  typeLabel: 'Harcanan Toplam Altın',
  unit: 'altın',
  mode: 'sum', // Tüm değerleri toplar
  icon: 'trophy'
);

📱 Ekran Analitiği

Kullanıcıların hangi sayfalarda ne kadar zaman geçirdiğini ölçmek çok önemlidir.

// Sayfa açıldığında çağırın (Örn: build metodunda veya Router içinde)
Flux.startScreen('ProductDetails');

// Sayfa kapandığında (Süre otomatik hesaplanır)
Flux.endScreen('ProductDetails');

🛠️ Hata ve Performans

Hataları yakalayarak kullanıcı deneyimini iyileştirin.

// 1. Manuel Error Takibi
try {
  // Riskli işlem...
} catch (e, stack) {
  Flux.trackError('Payment Failed', stackTrace: stack.toString(), metadata: {'code': '402'});
}

// 2. Otomatik Crash Raporlama
// main() içerisinde bir kez çağırırsanız tüm Flutter hatalarını yakalar.
Flux.autoTrackCrashes();

💡 En İyi Uygulamalar

İsimlendirme: typeLabel kısmında Türkçe karakter kullanabilirsiniz ancak eventName kısmında İngilizce, küçük harf ve alt tire (_) tercih edin.
Metadata: Analiz etmek istemediğiniz ama logda durmasını istediğiniz her şeyi metadata içine koyun.
Session: SDK, oturumları (session) otomatik yönetir. Kullanıcı uygulamadan çıkıp 30 dk sonra gelirse otomatik yeni bir session başlar.