Flutter için App Store Operator event rehberi

Durum: v1 taslağı, 2026-10-23. Burada anlatılan API planlandı ama henüz yayında değil. API yayına girince bu satırı kaldıracağız.

Kimin için: Bir Flutter uygulamasının iOS build'ine event takibi ekleyen Flutter geliştiricileri ve bu belgeyi verdikleri yapay zekâ kodlama ajanları. Entegrasyon için gereken her şey bu dosyada; bir ajan işi yalnızca bu dosyayla bitirebilir. App Store Operator şimdilik yalnızca iOS uygulamalarını destekliyor. Tracker, Android, web ve masaüstü build'lerinden hiçbir şey göndermez (Android desteği planlanıyor).

---

Yapay zekâ kodlama ajanıysanız önce burayı okuyun

Bir Flutter uygulamasına event takibi ekliyorsunuz. Uygulamanın sahibi bu event'lerle App Store Operator'da funnel'lar oluşturacak. Uygulamanın iOS build'i event'leri X-Write-Key header'ıyla POST https://api.app-store-operator.com/v1/events adresine gönderecek. Diğer platformlarda tracker hiçbir şey yapmaz.

Sırasıyla yapılacaklar

1. Yazma anahtarını alın. Bu belgede hâlâ YOUR_WRITE_KEY yazıyorsa anahtarı geliştiriciden isteyin (Dashboard → uygulama → Events → Setup; anahtar aso_wk_ ile başlar). Kendiniz anahtar uydurmayın, yer tutucuyu da kodda bırakmayın.
2. Tracker'ı ekleyin. §5'teki dört paketi flutter pub add ile ekleyin. Sonra §5'teki dosyayı hiç değiştirmeden lib/event_tracker.dart olarak projeye kopyalayın. iOS tarafında native extension'lar (widget, share, notification extension'ları) varsa onlardan event izlemeyin.
3. Uygulamaya bağlayın (§5.1). main() içinde, WidgetsFlutterBinding.ensureInitialized() çağrısından sonra configure(writeKey: ...)'u bir kez çağırın ve app_opened event'ini izleyin. Uygulama arka plana geçince flush() çağırın, arka plandan her dönüşte de app_opened event'ini tekrar izleyin.
4. track(...) çağrılarını ekleyin. §6'daki event'lerden akışı bu uygulamada olan her biri için bir çağrı ekleyin. Akışı olmayanları atlayın.
5. identify ve reset çağrılarını yalnızca uygulamanın kendi oturum açma (login) sistemi varsa ekleyin (§5.2).
6. Bitirince §9 Kontrol listesi'ni madde madde gözden geçirin. Her maddeyi tamamlandı, uygulanamaz veya beklemede olarak raporlayın ve yanına bunu gösteren dosyayı ve satırı yazın.

Kurallar

• lib/event_tracker.dart'ın davranışını (batch'leme, retry, endpoint, kuyruk, yalnızca iOS kontrolü) değiştirmeyin. Uygulamaya uymuyorsa dosyayı yeniden yazmayın, nedenini raporlayın.
• §5'teki dört paket (path_provider, shared_preferences, package_info_plus, device_info_plus) dışında üçüncü taraf bağımlılık eklemeyin. Uygulama bunlardan birini zaten kullanıyorsa olduğu gibi bırakın; sürüm çakışması olursa flutter pub add zaten uyarır.
• Tracker'ı Android, web veya masaüstünde çalışır hâle getirmeye uğraşmayın. App Store Operator şimdilik yalnızca iOS install'larını sayıyor.
• Kişiyi doğrudan tanımlayan hiçbir veri göndermeyin: ad, e-posta, telefon numarası, hassas konum, IDFA veya kullanıcının yazdığı metin (§7). Uygulama App Store'da Kids kategorisindeyse durun ve geliştiriciye bu tracker'ın eklenmemesi gerektiğini söyleyin (§7.8). Uygulama analitik için kullanıcıdan onay alıyorsa, izlemenin bu onayı bekleyip beklemeyeceğini geliştiriciye sorun (§7.5).
• Property değerleri düz olmalı: String, int, double, bool veya null. İç içe map veya liste göndermeyin (§4.3); tracker başka türdeki değerleri atar.
• §6'daki event adlarını birebir kullanın. §6'da olmayan bir akışa event adı koymadan önce geliştiriciye sorun.
• identify'a yalnızca uygulamanın kendi kalıcı, dahili kullanıcı ID'sini verin; e-posta, telefon numarası veya ad asla vermeyin. Hangi ID olduğundan emin değilseniz sorun.
• Dosyanın en üstündeki durum satırı duruyorsa API henüz yayında değil demektir. Yine her şeyi kurup bağlayın, ama §9'daki ağ kontrollerini beklemede olarak raporlayın. İsteğin başarısız olması kodunuzda hata olduğu anlamına gelmez.

Yazma anahtarı bilerek herkese açık tasarlandı (yalnızca tek bir uygulamaya event yazabilir). Bu yüzden kaynak kodda durmasında sakınca yok.

---

1. Temel bilgiler

2. Nasıl çalışır

1. Uygulama ilk açılışta rastgele bir anonim ID üretir ve saklar.
2. Takip etmek istediğiniz her eylem bir event olur. Event'in bir adı, bir zamanı, isteğe bağlı property'leri ve biraz device bilgisi vardır.
3. Event'ler device'ta kuyruğa girer ve batch'ler hâlinde gönderilir. Device çevrimdışıysa event'ler bekler, bağlantı gelince gönderilir.
4. Kullanıcı sizin uygulamanızda oturum açınca ona bir kullanıcı ID'si verebilirsiniz. Bundan sonraki event'ler iki ID'yi de taşır. App Store Operator da oturum açmadan önceki anonim event'leri ve sonrakileri aynı kişiye ait sayar.
5. Event'lerin canlı olarak geldiğini Dashboard'da görürsünüz ve bunlardan funnel'lar kurarsınız. Funnel, tekil kişi sayısıyla ölçülen sıralı adımlardır; örneğin onboarding_started → paywall_viewed → purchase_completed.

3. Yazma anahtarınızı alın

1. App Store Operator Dashboard'unda Uygulamalar → uygulamanız → Events → Setup'ı açın.
2. Yazma anahtarını kopyalayın (aso_wk_ ile başlar).
3. Anahtarı terminalden (macOS veya Linux) deneyin. Komut her seferinde yeni bir event_id ve o anki zamanı ürettiği için istediğiniz kadar çalıştırabilirsiniz:

curl -sS https://api.app-store-operator.com/v1/events \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_WRITE_KEY" \
  -d '{
    "events": [{
      "event_id": "'"$(uuidgen)"'",
      "name": "integration_test",
      "anonymous_id": "curl-test",
      "occurred_at": "'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'",
      "properties": { "source": "curl" }
    }]
  }'

Yanıtta accepted değeri 1, rejected ise boş olmalı. Event birkaç saniye içinde Events → Canlı'da görünür.

Neden her seferinde yeni değer? Aynı event_id yalnızca bir kez saklanır; aynı ID ile ikinci kez çalıştırırsanız Canlı'da yeni bir şey görmezsiniz. 7 günden eski bir zaman gönderirseniz de onun yerine event'in bize ulaştığı zamanı yazarız.

3.1 Anahtarı yenileme

Anahtarı yalnızca kötüye kullanılıyorsa yenileyin, örneğin biri bu anahtarla sahte event'ler gönderiyorsa. Anahtar zaten herkese açık; uygulamanızın içinden görülebiliyor olması yenilemek için bir neden değil.

1. Setup → Anahtarı yenile'ye tıklayın. Bunu çalışma alanındaki herkes yapabilir ve işlem kayda geçer.
2. Yeni anahtarı uygulamaya koyun ve bir güncelleme yayınlayın.
3. Kullanıcılar güncellemeye vakit bulsun diye eski anahtar 30 gün daha çalışır. Bu süreden sonra eski anahtarı kullanan build'ler 401 alır ve referans kod bu build'lerin event'lerini atar. Bu build'leri kullananlar güncelleyene kadar sayılmaz.
4. Eski anahtar hâlâ kötüye kullanılıyorsa Setup → Eski anahtarı şimdi iptal et ile 30 günlük süreyi hemen bitirin. Bundan sonra eski anahtarı kullanan build'ler sayılmaz. Bunu da çalışma alanındaki herkes yapabilir ve işlem kayda geçer.
5. Eski anahtarın 30 günü dolmadan Anahtarı yenile tekrar kullanılamaz. Bir daha yenilemek için önce eski anahtarı iptal edin ya da 30 günün dolmasını bekleyin.

4. API referansı

4.1 POST /v1/events

Tek istekte 1 ile 100 arası event gönderir.

Header'lar

Gövde

{
  "events": [ <event object>, ... ]
}

Gövde en fazla 1 MB olabilir. Gövdede veya event'lerde tanınmayan alanlar yok sayılır.

4.2 Yanıt

Batch'in kendisi geçerliyse, içindeki bazı event'ler reddedilse bile yanıt 200 OK olur:

{
  "accepted": 2,
  "rejected": [
    { "index": 2, "event_id": "…", "code": "invalid_name", "message": "Event name must match ^[A-Za-z0-9_.:-]{1,64}$" }
  ],
  "clamped": [
    { "index": 0, "event_id": "…" }
  ]
}

• accepted: saklanan event'ler. Daha önce saklanmış tekrar event'ler de buna dahil (event_id'ye bakın).
• rejected: saklanmayan event'ler. Bunları değiştirmeden tekrar göndermeyin.
• clamped: occurred_at değeri izin verilen aralığın dışında kaldığı için yerine sunucuya ulaşma zamanı yazılan event'ler. Bunlar da saklanır ve accepted'a dahildir.

Üç alan da her yanıtta vardır; rejected ve clamped boş olabilir.

4.3 Event nesnesi

context

Her context değeri en fazla 64 karakterlik bir string olmalı. Bu kurala uymayan değerler ve tabloda olmayan anahtarlar atılır; event'in kendisi reddedilmez.

Sunucu, isteğin geldiği ağ konumuna bakarak country alanını ekler. IP adresi hiçbir zaman saklanmaz.

Serialize edilmiş bir event en fazla 8 KB olabilir.

Tam örnek

{
  "event_id": "0b6f6a3e-3c3e-4d8a-8f6e-1f9b8a2c7d10",
  "name": "purchase_completed",
  "anonymous_id": "C5E1B0B2-4F7A-4E0F-9C1D-2A6B7E8F9012",
  "user_id": "u_81723",
  "occurred_at": "2026-10-23T12:04:31.512Z",
  "properties": {
    "product_id": "pro_yearly",
    "price": 39.99,
    "currency": "USD",
    "trial": true
  },
  "context": {
    "app_version": "2.4.0",
    "build": "412",
    "os_version": "18.1",
    "device_model": "iPhone16,2",
    "locale": "en_US",
    "environment": "app_store"
  }
}

4.4 POST /v1/identify (isteğe bağlı)

Event göndermeden bir anonim ID'yi bir kullanıcı ID'sine bağlar. Buna pek ihtiyacınız olmaz, çünkü iki ID'yi de taşıyan her event aynı işi görür. Eşleşmeyi yalnızca sunucunuz biliyorsa kullanın.

{ "anonymous_id": "C5E1B0B2-4F7A-4E0F-9C1D-2A6B7E8F9012", "user_id": "u_81723" }

Yanıt: 204 No Content. Bir anonim ID için ilk eşleşme geçerlidir; aynı anonim ID'ye sonradan gelen farklı kullanıcı ID'leri yok sayılır.

4.5 Hatalar

Hata gövdesi: { "code": "invalid_write_key", "message": "…" }.

Event bazında ret kodları (200 yanıtının içinde döner):

Kısaca retry kuralı: ağ hatasında, 429'da ve 5xx'te aynı event_id'lerle tekrar deneyin. Diğer bütün durumlarda batch'i atın.

5. Referans kod

Tek bir Dart dosyası. Projeye lib/event_tracker.dart olarak ekleyin ve hiç değiştirmeden kullanın. Dört pakete ihtiyacı var, fazlasına değil:

flutter pub add path_provider shared_preferences package_info_plus device_info_plus

flutter pub add en güncel sürümleri seçer. Kodu şu sürümlerle test ettik (Flutter 3.44, Dart 3.12):

dependencies:
  path_provider: ^2.1.6
  shared_preferences: ^2.5.6
  package_info_plus: ^10.2.2
  device_info_plus: ^13.3.0

İstekler dart:io'daki HttpClient ile gider; ayrı bir HTTP paketine gerek yok.

Dosya şunları yapar:

• Yalnızca iOS'te çalışır. Android, web ve masaüstünde her metot hiçbir şey yapmadan hemen döner: ID yok, dosya yok, istek yok. App Store Operator şimdilik yalnızca iOS uygulamalarını destekliyor; bu sayede Android install'ları App Store funnel'larınıza karışmaz. Android desteği planlanıyor.
• İlk event izlendiğinde rastgele bir anonim ID (Random.secure() ile üretilen bir v4 UUID) üretir ve shared_preferences'ta saklar. currentAnonymousId bu ID'yi döndürür.
• setEnabled(...) ile izlemeyi açıp kapatabilirsiniz. Varsayılan olarak açıktır ve seçim uygulama yeniden açıldığında da hatırlanır. Kapatınca ID'ler ve gönderilmemiş bütün event'ler silinir; tekrar açılana kadar track hiçbir şey yapmaz.
• Her event'i diskteki bir kuyruk dosyasına yazar; uygulama kapansa da event'ler kaybolmaz.
• Kuyruğu en fazla 100 event'lik batch'ler hâlinde gönderir. Gönderim 30 saniyede bir, kuyrukta 20 veya daha fazla event biriktiğinde ve siz flush() çağırdığınızda olur.
• Çevrimdışıyken veya 5xx aldığında kuyruğu korur ve tekrar denemeden önce bekler: 30 saniye, sonra 60, 120… en fazla 10 dakika. 429 aldığında kuyruğu korur ve sunucunun Retry-After değeri kadar bekler. Başka bir yanıt gelirse batch'i kuyruktan çıkarır.
• Kuyrukta en fazla 1.000 event tutar; sınır aşılınca en eskileri atar.
• Yalnızca debug build'lerinde (kDebugMode), reddedilen ve clamp'lenen event'leri, atılan batch'leri ve attığı property değerlerini debugPrint ile Flutter konsoluna [EventTracker] … diye yazar. Release build'ler konsola hiçbir şey yazmaz.
• Debug ve profile build'lerinden gelen event'leri debug olarak etiketler; böylece testleriniz funnel'larınıza karışmaz. Release build'lerin event'leri ya configure'a verdiğiniz environment değerini taşır ya da hiç ortam bilgisi taşımaz (aşağıdaki Test build'leri kısmına bakın).
• track hemen döner, ağı hiç beklemez. configure, track, identify, reset ve setEnabled hangi sırayla çağrıldıysa o sırayla işlenir; sıra bozulmasın diye bunları await etmeniz gerekmez.

track'i configure'dan önce de çağırabilirsiniz; event'ler anahtar verilene kadar kuyrukta bekler.

Her uygulamaya bir anahtar. Dashboard'daki her uygulamanın kendi yazma anahtarı var. Bir anahtarı yalnızca kendi uygulamasının binary'sinde kullanın.

Extension'larda kullanmayın. iOS uygulamanızın native extension'ları (widget, share, notification extension'ları) varsa onlardan event izlemeyin. Extension'ların kendi depolama alanı vardır. Bu yüzden her biri kendi anonim ID'sini alır ve ayrı bir kişi olarak sayılır. Event'leri yalnızca Flutter uygulamasından izleyin.

Test build'leri. Flutter'da bir release build, native kod yazmadan TestFlight'ı App Store'dan ayırt edemez. Bu yüzden configure isteğe bağlı bir environment parametresi alır: "testflight" veya "app_store" (başka değerler yok sayılır; debug ve profile build'ler her zaman debug olur). §5.1'deki kod bu değeri build sırasında verilen bir define'dan okur:

flutter build ipa --dart-define=ASO_ENV=testflight

Define verilmezse release event'leri ortam bilgisi taşımaz ve Dashboard bunları App Store event'i sayar; TestFlight test kullanıcılarınınkiler de buna dahil. Dikkat: Apple, TestFlight'a yüklediğiniz build'in aynısını yayınlar. ASO_ENV=testflight ile alınmış bir build'i sonradan App Store'da yayınlarsanız etiket build'de kalır ve App Store kullanıcılarınız Dashboard'un varsayılan görünümünden kaybolur. Define'ı yalnızca hiç yayınlanmayacak build'lerde kullanın, örneğin ayrı bir dahili test build'inde.

import 'dart:async';
import 'dart:convert';
import 'dart:io';
import 'dart:math';

import 'package:device_info_plus/device_info_plus.dart';
import 'package:flutter/foundation.dart';
import 'package:package_info_plus/package_info_plus.dart';
import 'package:path_provider/path_provider.dart';
import 'package:shared_preferences/shared_preferences.dart';

/// Event'leri App Store Operator'a gönderir. Belgeler: https://app-store-operator.com/docs/events/flutter
///
/// Yalnızca iOS: Android, web ve masaüstünde hiçbir metot bir şey yapmaz.
class EventTracker {
  EventTracker._();

  static final EventTracker shared = EventTracker._();

  static final Uri _endpoint = Uri.parse('https://api.app-store-operator.com/v1/events');
  static const int _maxBatch = 100;
  static const int _maxQueue = 1000;
  static const int _flushAt = 20;
  static const String _anonymousIdKey = 'aso.events.anonymousId';
  static const String _userIdKey = 'aso.events.userId';
  static const String _disabledKey = 'aso.events.disabled';
  static const Set<String> _environments = {'debug', 'testflight', 'app_store'};

  static final bool _supported = !kIsWeb && defaultTargetPlatform == TargetPlatform.iOS;
  static final Random _random = Random.secure();

  late final Future<void> _ready = _load(); // ilk çağrıyla başlar
  final HttpClient _http = HttpClient()..connectionTimeout = const Duration(seconds: 30);

  SharedPreferencesWithCache? _prefs;
  File? _store;
  Map<String, String> _context = const {};
  String? _writeKey;
  String? _environment;
  String? _anonymousId;
  String? _userId;
  bool _enabled = true;
  List<Map<String, Object?>> _queue = [];
  bool _flushing = false;
  Timer? _timer;
  DateTime? _retryAt;
  int _backoff = 0; // saniye
  Future<void>? _writing;
  bool _dirty = false;
  bool _warned = false;

  /// Açılışta, `WidgetsFlutterBinding.ensureInitialized()` sonrasında bir kez çağırın.
  ///
  /// Debug ve profile build'leri `debug` olarak işaretlenir. Release build'leri, verilirse [environment]
  /// (`testflight` veya `app_store`) ile işaretlenir; verilmezse ortam taşımaz.
  void configure({required String writeKey, String? environment}) {
    if (!_isSupported()) return;
    _writeKey = writeKey;
    if (!kReleaseMode) {
      _environment = 'debug';
    } else if (environment != null && _environments.contains(environment)) {
      _environment = environment;
    }
    _timer ??= Timer.periodic(const Duration(seconds: 30), (_) => flush());
    unawaited(_ready);
  }

  /// Bu install'ın kimliği; ilk izlenen event'ten önce ve izleme kapalıyken null.
  /// Kullanıcının verilerinin silinmesini isteyebilmesi için bir destek ekranında gösterin.
  Future<String?> get currentAnonymousId async {
    if (!_isSupported()) return null;
    await _ready;
    return _anonymousId;
  }

  /// İzlemeyi açar veya kapatır ve seçimi açılışlar arasında hatırlar. İzleme varsayılan olarak açıktır.
  /// Kapatmak bu install'ın kimliklerini ve henüz gönderilmemiş tüm event'leri siler; ardından `track` hiçbir şey yapmaz.
  /// Uygulamanız önce kullanıcının onayını almak zorundaysa, kullanıcı kabul edene kadar açılışta `setEnabled(false)` çağırın.
  Future<void> setEnabled(bool enabled) async {
    if (!_isSupported()) return;
    await _ready;
    _enabled = enabled;
    unawaited(_prefs?.setBool(_disabledKey, !enabled));
    if (enabled) return;
    _anonymousId = null;
    _userId = null;
    _queue = [];
    unawaited(_prefs?.remove(_anonymousIdKey));
    unawaited(_prefs?.remove(_userIdKey));
    _persist(); // boş kuyruk dosyayı siler
  }

  /// Bir event kaydeder. Hafiftir; hemen döner ve asla ağı beklemez.
  /// İzleme kapalıyken hiçbir şey yapmaz. Property değerleri: String, int, double, bool veya null.
  void track(String name, [Map<String, Object?> properties = const {}]) {
    if (!_isSupported()) return;
    final eventId = _uuid();
    final occurredAt = _now();
    final props = _flat(name, properties);
    unawaited(_ready.then((_) {
      if (!_enabled) return;
      _queue.add({
        'event_id': eventId,
        'name': name,
        'anonymous_id': _anonymousId ?? _newAnonymousId(),
        if (_userId != null) 'user_id': _userId,
        'occurred_at': occurredAt,
        'properties': props,
        'context': _context,
      });
      if (_queue.length > _maxQueue) _queue.removeRange(0, _queue.length - _maxQueue);
      _persist();
      if (_queue.length >= _flushAt) unawaited(flush());
    }));
  }

  /// Kullanıcı uygulamanızda oturum açtıktan sonra çağırın. Kendi kalıcı kullanıcı kimliğinizi kullanın, asla e-posta değil.
  Future<void> identify(String userId) async {
    if (!_isSupported()) return;
    await _ready;
    if (!_enabled) return;
    _userId = userId;
    unawaited(_prefs?.setString(_userIdKey, userId));
  }

  /// Oturum kapatılırken çağırın: sonraki event'ler yeni bir anonim kişiye ait olur.
  Future<void> reset() async {
    if (!_isSupported()) return;
    await _ready;
    _userId = null;
    _anonymousId = null;
    unawaited(_prefs?.remove(_userIdKey));
    unawaited(_prefs?.remove(_anonymousIdKey));
  }

  /// Kuyruktaki event'leri gönderir. Bir yeniden deneme beklemesi sürerken hiçbir şey yapmaz.
  Future<void> flush() async {
    if (!_isSupported()) return;
    await _ready;
    final writeKey = _writeKey;
    if (!_enabled || _flushing || writeKey == null || _queue.isEmpty) return;
    final retryAt = _retryAt;
    if (retryAt != null && retryAt.isAfter(DateTime.now())) return;
    _flushing = true;
    try {
      while (_queue.isNotEmpty) {
        final batch = _queue.take(_maxBatch).toList();
        final events = [
          for (final event in batch)
            {
              ...event,
              'context': {
                if (_environment != null) 'environment': _environment,
                ...(event['context'] as Map? ?? const {}),
              },
            },
        ];
        final response = await _post(writeKey, jsonEncode({'events': events}));
        if (response == null) {
          _delayRetry(null); // çevrimdışı: kuyruğu tut
          return;
        }
        if (!_enabled) return; // gönderim sırasında kapatıldı: kuyruk zaten silindi
        final (status, retryAfter, body) = response;
        if (status == 429 || status >= 500) {
          _delayRetry(status == 429 ? double.tryParse(retryAfter ?? '') : null); // kuyruğu tut
          return;
        }
        _retryAt = null;
        _backoff = 0;
        if (kDebugMode) _report(status, body);
        // 2xx: saklandı. Diğer 4xx: aynı batch'i tekrar denemenin anlamı yok.
        final sent = {for (final event in batch) event['event_id']};
        _queue.removeWhere((event) => sent.contains(event['event_id']));
        _persist();
      }
    } finally {
      _flushing = false;
    }
  }

  Future<void> _load() async {
    try {
      final prefs = await SharedPreferencesWithCache.create(
        cacheOptions: const SharedPreferencesWithCacheOptions(
          allowList: {_anonymousIdKey, _userIdKey, _disabledKey},
        ),
      );
      _prefs = prefs;
      _enabled = !(prefs.getBool(_disabledKey) ?? false);
      _anonymousId = prefs.getString(_anonymousIdKey); // ilk izlenen event'le oluşturulur
      _userId = prefs.getString(_userIdKey);
    } catch (error) {
      _debug('settings unavailable, keeping IDs in memory: $error');
    }

    try {
      final dir = await getApplicationSupportDirectory();
      await dir.create(recursive: true);
      final store = File('${dir.path}/aso-events-queue.json');
      _store = store;
      if (await store.exists()) {
        final saved = jsonDecode(await store.readAsString()) as List<dynamic>;
        _queue = [for (final event in saved) Map<String, Object?>.from(event as Map)];
      }
    } catch (error) {
      _debug('queue file unavailable, keeping events in memory: $error');
    }

    var appVersion = '', build = '', osVersion = '', deviceModel = '';
    try {
      final package = await PackageInfo.fromPlatform();
      appVersion = package.version;
      build = package.buildNumber;
    } catch (_) {}
    try {
      final ios = await DeviceInfoPlugin().iosInfo;
      osVersion = ios.systemVersion;
      deviceModel = ios.utsname.machine;
    } catch (_) {}
    _context = {
      'app_version': appVersion,
      'build': build,
      'os_version': osVersion,
      'device_model': deviceModel,
      'locale': PlatformDispatcher.instance.locale.toString(), // en_US
    };
  }

  Future<(int, String?, String)?> _post(String writeKey, String body) async {
    try {
      return await () async {
        final request = await _http.postUrl(_endpoint);
        request.headers.contentType = ContentType.json;
        request.headers.set('X-Write-Key', writeKey);
        request.add(utf8.encode(body));
        final response = await request.close();
        final text = await response.transform(utf8.decoder).join();
        return (response.statusCode, response.headers.value('retry-after'), text);
      }().timeout(const Duration(seconds: 60));
    } catch (_) {
      return null;
    }
  }

  /// Sunucu belirtirse `seconds` kadar, aksi hâlde 30 sn, 60 sn, 120 sn… en fazla 10 dakika bekler.
  void _delayRetry(double? seconds) {
    _backoff = min(max(_backoff * 2, 30), 600);
    final wait = Duration(milliseconds: ((seconds ?? _backoff) * 1000).round());
    _retryAt = DateTime.now().add(wait);
  }

  /// Kuyruğu diske her seferinde tek bir yazmayla yazar; son yazma her zaman en güncel kuyruğu içerir.
  void _persist() {
    if (_store == null) return;
    _dirty = true;
    _writing ??= _write();
  }

  Future<void> _write() async {
    while (_dirty) {
      _dirty = false;
      final store = _store!;
      try {
        if (_queue.isEmpty) {
          if (await store.exists()) await store.delete();
        } else {
          final temp = File('${store.path}.tmp');
          await temp.writeAsString(jsonEncode(_queue), flush: true);
          await temp.rename(store.path);
        }
      } catch (_) {}
    }
    _writing = null;
  }

  String _newAnonymousId() {
    final id = _uuid();
    _anonymousId = id;
    unawaited(_prefs?.setString(_anonymousIdKey, id));
    return id;
  }

  /// String, int, sonlu double, bool ve null değerleri tutar; diğer her şeyi atar.
  Map<String, Object?> _flat(String name, Map<String, Object?> properties) {
    final result = <String, Object?>{};
    properties.forEach((key, value) {
      if (value == null || value is String || value is int || value is bool ||
          (value is double && value.isFinite)) {
        result[key] = value;
      } else {
        _debug('$name: property "$key" dropped, ${value.runtimeType} is not a flat value');
      }
    });
    return result;
  }

  /// Yalnızca debug build'lerde: atılan batch'leri ve reddedilen veya clamp'lenen event'leri Flutter konsoluna yazdırır.
  void _report(int status, String body) {
    Object? json;
    try {
      json = jsonDecode(body);
    } catch (_) {}
    if (status < 200 || status >= 300) {
      _debug('HTTP $status, batch dropped: ${json ?? body}');
      return;
    }
    if (json is! Map) return;
    for (final key in ['rejected', 'clamped']) {
      final items = json[key];
      if (items is List && items.isNotEmpty) _debug('$key: $items');
    }
  }

  bool _isSupported() {
    if (_supported) return true;
    if (!_warned) {
      _warned = true;
      _debug('iOS only: tracking is off on ${kIsWeb ? 'web' : defaultTargetPlatform.name}');
    }
    return false;
  }

  static void _debug(String message) {
    if (kDebugMode) debugPrint('[EventTracker] $message');
  }

  static String _now() {
    final now = DateTime.now().millisecondsSinceEpoch;
    return DateTime.fromMillisecondsSinceEpoch(now, isUtc: true).toIso8601String();
  }

  /// Rastgele (sürüm 4) bir UUID.
  static String _uuid() {
    final bytes = List<int>.generate(16, (_) => _random.nextInt(256));
    bytes[6] = (bytes[6] & 0x0f) | 0x40;
    bytes[8] = (bytes[8] & 0x3f) | 0x80;
    final hex = bytes.map((b) => b.toRadixString(16).padLeft(2, '0')).join();
    return '${hex.substring(0, 8)}-${hex.substring(8, 12)}-${hex.substring(12, 16)}-'
        '${hex.substring(16, 20)}-${hex.substring(20)}';
  }
}

5.1 Uygulamaya bağlama

import 'dart:async';

import 'package:flutter/widgets.dart';

import 'event_tracker.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  EventTracker.shared.configure(
    writeKey: 'YOUR_WRITE_KEY',
    environment: const String.fromEnvironment('ASO_ENV'), // bkz. §5'teki "Test build'leri"
  );
  EventTracker.shared.track('app_opened', {'source': 'cold'});

  var wasInBackground = false;
  // Uygulama çalıştığı sürece kayıtlı kalır; referans tutmanız gerekmez.
  AppLifecycleListener(
    onHide: () {
      // Uygulama arka plana geçiyor: kuyruktakileri gönder.
      wasInBackground = true;
      unawaited(EventTracker.shared.flush());
    },
    onResume: () {
      if (!wasInBackground) return; // uyarılar, Denetim Merkezi ve Face ID uygulamayı yalnızca etkin olmayan duruma getirir
      wasInBackground = false;
      EventTracker.shared.track('app_opened', {'source': 'warm'});
    },
  );

  runApp(const MyApp());
}

main()'de başka kurulum kodu varsa olduğu gibi bırakın; bu çağrıları WidgetsFlutterBinding.ensureInitialized()'dan sonra, runApp'ten önce koyun. Tracker, sakladığı ID'leri ve device bilgilerini binding'e ihtiyaç duyan plugin'lerle okur. AppLifecycleListener için Flutter 3.13 veya üstü gerekir. Uygulamada zaten bir WidgetsBindingObserver varsa onu da kullanabilirsiniz: AppLifecycleState.hidden'da flush() çağırın, sonraki resumed'da warm app_opened event'ini izleyin.

app_opened her resume'da değil, yalnızca arka plandan dönüşte gönderilir. Çünkü sistem uyarıları, Denetim Merkezi ve Face ID de uygulamayı gizlemeden inactive yapıp tekrar active yapar.

Arka plan süresi. iOS, arka plana geçen uygulamaya birkaç saniye verir; flush()'ın bitmesi için bu genelde yeterlidir. Flutter uygulaması native kod olmadan iOS'ten ek süre isteyemez. Uygulama daha önce askıya alınırsa event'ler kuyruk dosyasında kalır ve bir sonraki açılışta gider.

5.2 Event takibi

EventTracker.shared.track('paywall_viewed', {'placement': 'onboarding'});
EventTracker.shared.track('onboarding_completed', {'duration_s': 42});

// Değişkenler de aynı şekilde çalışır: String, int, double, bool veya null değerler.
EventTracker.shared.track('onboarding_step_viewed', {'step': step, 'step_name': stepName});

// Uygulamanızda oturum açıldıktan / kapatıldıktan sonra:
await EventTracker.shared.identify(user.id);
await EventTracker.shared.reset();

// Onay ya da uygulama içi "Analitik verilerini paylaş" ayarı: açılışta, configure ve ilk track'ten önce
// kullanıcının güncel seçimiyle çağırın; seçim değiştikçe tekrar çağırın.
await EventTracker.shared.setEnabled(userAllowsAnalytics);

// Destek ekranı: kullanıcı verilerinin silinmesini isteyebilsin diye bunu gösterin (henüz hiçbir şey izlenmediyse null).
final installId = await EventTracker.shared.currentAnonymousId;

İzleme kullanıcı onayına bağlıysa setEnabled'ı §5.1'deki açılış app_opened event'inden önce çağırın. İzleme kapalıyken o çağrı hiçbir şey yapmaz ve ID üretilmez.

Property değerleri String, int, double, bool veya null olmalı. Tracker başka türdeki değerleri (DateTime, enum, iç içe map veya liste, double.nan) atar ve debug build'de [EventTracker] … dropped yazar. Bu değerleri önce dönüştürün: date.toIso8601String(), plan.name.

Satın almalar. Satın almaları, kullanıcının satın al butonuna bastığı akışın içinde izleyin. Satın alma çağrınızı şu wrapper ile sarın:

/// Satın almanın nasıl sonuçlandığı, satın alma kodunuzun bildirdiği şekliyle.
enum PurchaseOutcome { success, cancelled, pending, failed }

/// Satın alma çağrınızı sarar. [purchase] onu çalıştırır ve nasıl sonuçlandığını bildirir.
Future<void> buy({
  required String productId,
  required double price,
  required String currency,
  required bool startsTrial,
  required Future<PurchaseOutcome> Function() purchase,
}) async {
  final base = {'product_id': productId};
  EventTracker.shared.track('purchase_started', base);
  PurchaseOutcome outcome;
  try {
    outcome = await purchase();
  } catch (_) {
    outcome = PurchaseOutcome.failed;
  }
  switch (outcome) {
    case PurchaseOutcome.success:
      EventTracker.shared.track('purchase_completed', {
        ...base,
        'price': price,
        'currency': currency,
        'trial': startsTrial,
      });
      if (startsTrial) EventTracker.shared.track('trial_started', base);
    case PurchaseOutcome.cancelled:
      EventTracker.shared.track('purchase_failed', {...base, 'reason': 'cancelled'});
    case PurchaseOutcome.failed:
      EventTracker.shared.track('purchase_failed', {...base, 'reason': 'failed'});
    case PurchaseOutcome.pending:
      break; // Ask to Buy veya ek onay: henüz tamamlanmadı, hiçbir şey izlemeyin
  }
}

purchase, store kütüphanenizin satın alma metodunu saran kendi fonksiyonunuz. Satın alma tamamlanıp doğrulandıysa success, kullanıcı vazgeçtiyse cancelled, Ask to Buy veya başka bir onay bekleniyorsa pending, diğer durumlarda failed döndürmeli (exception fırlatmak da failed sayılır). price (formatlanmış bir string değil, sayı) ve currency ("USD" gibi bir ISO 4217 kodu) ürün bilgilerinizden gelir. startsTrial ise paywall'unuzun zaten bildiği bir değer: bu satın alma ücretsiz trial başlatıyorsa true.

• in_app_purchase: buyNonConsumable ve buyConsumable satın almayı yalnızca başlatır; sonuç purchaseStream'den gelir. purchase fonksiyonunuz satın almayı başlatıp o ürün için gelen ilk güncellemeyi beklesin. Eşleme şöyle: PurchaseStatus.purchased → success, canceled → cancelled, pending → pending, error → failed. Fiyat ve para birimi için ProductDetails.rawPrice ve currencyCode'u kullanın.
• RevenueCat (purchases_flutter): satın alma metotları satın alma tamamlanınca döner, tamamlanmazsa PlatformException fırlatır. PurchasesErrorCode.purchaseCancelledError'ı cancelled, paymentPendingError'ı pending, diğer hataları failed olarak eşleyin.
• Diğer kütüphaneler: aynı çağrıları kütüphanenin satın alma metodunun etrafına koyun.

Satın almaları, in_app_purchase'ın purchaseStream listener'ı gibi her transaction'ı alan bir listener'da izlemeyin. Oraya geri yüklenen satın almalar (PurchaseStatus.restored), yenilemeler ve sonraki bir açılışta tamamlanan satın almalar da düşer ve hepsi yeni satın alma gibi sayılır.

6. Hangi event'ler izlenmeli

Bir funnel, arkasındaki event'ler kadar iyidir. Aşağıdaki event'lerle başlayın, yeni sorular çıktıkça yenilerini ekleyin.

Adlandırma kuralları

• snake_case, object_action, geçmiş zaman: paywall_viewed, purchase_completed.
• Her eyleme tek bir ad verin. Farklılıkları adda değil (settings_paywall_viewed), property'lerde tutun (placement: "settings" ile paywall_viewed).
• Ada ID, tarih veya kullanıcı verisi koymayın.
• Funnel'ı bir property'ye göre bölmek istiyorsanız o property'ye serbest metin değil, az sayıda sabit değer verin (plan: "yearly"). Dashboard en sık görülen 10 değeri gösterir, gerisini "Diğer" altında toplar.
• Adlar ve property değerleri büyük/küçük harfe duyarlıdır: Paywall_Viewed ile paywall_viewed iki ayrı event'tir.

Önerilen başlangıç seti

Akışı uygulamanızda olan event'leri izleyin, gerisini atlayın. isteğe bağlı diye işaretli property'leri göndermeyebilirsiniz.

Uygulama event'lerinin göremedikleri. Yenilemeler, ücretli subscription'a dönen trial'lar, iptaller ve refund'lar Apple tarafında, çoğu zaman uygulamanız kapalıyken olur. Uygulama bunları hiç görmediği için bu event'lerde de yoklar. Buradaki funnel'lar satın almada veya trial başlangıcında biter.

Bu event'lerle kurabileceğiniz örnek funnel'lar

7. Gizlilik

Bu bölüm hukuki tavsiye değil, yol göstermek için var. Uygulamanızın ne gönderdiğini ve kullanıcılarınızın nerede olduğunu siz biliyorsunuz. Son karar sizin; mümkünse hukuk danışmanınızla birlikte verin.

Bu bölümdeki her konu için gizlilik iletişim adresimiz: [email protected].

7.1 App Store Operator'a ulaşan veriler

• Event adları ve property'leri.
• anonymous_id: rastgele bir UUID. Referans kod bunu izleme açıkken ilk event'te üretir ve izleme kapatılana veya reset çağrılana kadar o install için saklar. IDFA değildir, başka uygulamalarla paylaşılan bir tanımlayıcı da değildir.
• user_id (yalnızca identify çağırırsanız).
• §4.3'teki device bilgileri: uygulama version'ı, build, işletim sistemi sürümü, device modeli, dil ve bölge ayarı ve build ortamı.
• İsteğin geldiği ağ konumundan çıkarılan ülke (§7.3).

Referans kod event'leri yalnızca iOS build'inden gönderir; Android, web ve masaüstü build'leri hiçbir şey göndermez.

Asla göndermeyin: ad, e-posta, telefon numarası, hassas konum, IDFA veya kullanıcının yazdığı serbest metin. Bunlar ne event adında, ne property'lerde, ne de user_id'de olmalı. user_id uygulamanızın kendi dahili ID'si olmalı (örneğin bir veritabanı anahtarı); e-posta, telefon numarası veya başka bir şirketin verdiği bir ID olmamalı.

7.2 Roller ve hizmet sağlayıcılar

• Roller. Uygulamanızın gönderdiği event'lerin veri sorumlusu (KVKK'daki adıyla veri sorumlusu) sizsiniz: neyin, neden toplanacağına siz karar verirsiniz. App Store Operator'ı işleten Nefarius ise event'leri saklamak ve Dashboard'da size göstermek için sizin adınıza işler; yani veri işleyendir (KVKK'daki adıyla veri işleyen).
• Yapmadıklarımız. Event verilerini satmayız, reklam için kullanmayız ve başka müşterilerle paylaşmayız.
• Hizmet sağlayıcılar (alt işleyenler). Barındırılan her hizmet gibi biz de event verilerini yalnızca bizim adımıza işleyen sağlayıcılarla çalışırız:
  • Cloudflare: ağ iletimi ve güvenlik. Uygulamanızdan gelen her istek Cloudflare'den geçer.
  • Sunucu barındırma sağlayıcımız: sunucuları ve event'lerin saklandığı veritabanını çalıştırır.
• Konumlar. Cloudflare dünyanın her yerinde çalıştığı için bir istek, kullanıcınızın bulunduğu ülkenin dışında işlenebilir.
• Veri işleme sözleşmesi (DPA). DPA (örneğin GDPR madde 28 kapsamında), hizmet sağlayıcıların konumlarıyla güncel listesi veya yurt dışına aktarım güvencelerinin ayrıntıları gerekiyorsa yukarıdaki gizlilik adresine yazın.

7.3 IP adresi ve ülke

Uygulamanızın istekleri bize Cloudflare üzerinden gelir. Cloudflare isteği iletmek için IP adresine ihtiyaç duyar ve ülkeyi bu adresten bulur. App Store Operator yalnızca ülkeyi saklar (şehir veya bölge saklamaz); IP adresini hiçbir zaman saklamaz ve loglamaz.

7.4 Saklama süresi ve silme talepleri

• Event'ler 13 ay saklanır, sonra otomatik olarak silinir.
• Tek bir kişinin event'lerini Dashboard'dan silmek henüz mümkün değil. Bu özellik gelene kadar, bir kullanıcı verilerinin silinmesini isterse (örneğin GDPR madde 17 veya KVKK madde 11 kapsamında) App Store Operator çalışma alanınızdaki birinin e-posta adresinden yukarıdaki gizlilik adresine yazın. E-postaya şunları ekleyin:
  • Uygulamanın Dashboard'da görünen adı;
  • Kişinin user_id'si ve/veya anonymous_id'si. Bir user_id, ona bağlı bütün anonymous_id'leri de kapsar. Hesabı olmayan kullanıcılar için anonymous_id'yi await EventTracker.shared.currentAnonymousId ile alıp örneğin bir destek ekranında gösterebilirsiniz (§5.2). Bu değeri setEnabled(false) veya reset() çağırmadan önce okuyun. İkisi de değeri device'tan siler ve bu değer olmadan o install'ın event'lerini bulamayız.
• Bu ID'leri taşıyan bütün event'leri siler, sonucu e-postayla bildiririz. Talepleri bekletmeden gönderin; kullanıcıya yanıt vermek için sizin de yasal bir süreniz var (GDPR'da genelde bir ay, KVKK'da 30 gün).
• Çalışma alanınızın üyesi olmayan birinden gelen talepleri işleme almayız; o kişiyi size yönlendiririz.

7.5 Gizlilik politikanız ve kullanıcı onayı

• Gizlilik politikası. Uygulamanızın gizlilik politikasında şunlar yazmalı: kullanım analitiği topladığınız, bunun hangi verileri kapsadığı (§7.1), bu verileri sizin adınıza bir hizmet sağlayıcının (Nefarius'un işlettiği App Store Operator) işlediği ve verilerin 13 ay saklandığı.
• Hukuki dayanak ve onay. Analitiğin hukuki dayanağına ve önce kullanıcıdan onay (açık rıza) almanız gerekip gerekmediğine siz karar verirsiniz. AB ve Birleşik Krallık'ta analitik için device'ta bir tanımlayıcı saklamak veya okumak çoğu zaman onay gerektirir; KVKK'da ise kullanıcıyı en azından bilgilendirmeniz gerekir. Onay gerekiyorsa açılışta her şeyden önce EventTracker.shared.setEnabled(false) çağırın, kullanıcı kabul edene kadar öyle kalsın, kabul edince de setEnabled(true) çağırın (§5.2). İzleme kapalıyken device'ta hiçbir ID veya event saklanmaz (yalnızca "kapalı" ayarının kendisi saklanır) ve hiçbir şey gönderilmez. Tracker anonymous_id'yi yalnızca izleme açıkken ilk event'te üretir. Kullanıcı onayını sonradan geri çekerse setEnabled(false) izlemeyi durdurur, device'taki ID'leri ve gönderilmemiş event'leri siler. Daha önce gönderilmiş event'leri ise silmez. Tek hukuki dayanağınız onaysa veya kullanıcı silinmelerini isterse önce currentAnonymousId değerini okuyun, sonra §7.4'teki gibi silme talebi gönderin.

7.6 App Tracking Transparency

App Store Operator event'lerinizi reklam veya reklam ölçümü için başka şirketlerin uygulamalarından, sitelerinden ya da çevrimdışı kaynaklarından gelen verilerle birleştirmez. Event'leri veri simsarlarıyla paylaşmaz, device bilgilerini fingerprinting için kullanmaz. Bu yüzden entegrasyon tek başına Apple'ın tanımıyla tracking sayılmaz ve App Tracking Transparency (ATT) izni gerektirmez.

ATT kararı entegrasyon başına değil, uygulamanın tamamı için verilir. Uygulamanız veya içindeki başka bir SDK bu event'leri ya da user_id'nizi reklam veya reklam ölçümü için başka şirketlerin verileriyle eşliyorsa ya da bir veri simsarıyla paylaşıyorsa bu tracking olur. O zaman önce kullanıcıdan ATT izni almanız gerekir ve gizlilik etiketinizde verilerin tracking için kullanıldığı yazmalıdır. Ayrıntılar için Apple'ın User Privacy and Data Use sayfasına bakın.

7.7 App Store gizlilik etiketi ve gizlilik manifesti

Apple'ın gizlilik sorularını uygulamanın tamamı için yanıtlarsınız. Apple, eklediğiniz üçüncü taraf kodların topladığı verileri de saymanızı ister; bu kod da onlardan biri. App Store Operator'a giden veriler için genelde şu yanıtlar verilir:

• Linked to You. user_id gönderiyorsanız yukarıdaki bütün satırları Linked to You olarak beyan edin, çünkü event'ler sisteminizdeki bir hesap ID'siyle eşleşir. Hiç user_id göndermiyorsanız ve event'leri başka bir yerde de bir hesaba veya kimliği belli eden başka verilere bağlamıyorsanız, veri yalnızca rastgele bir install ID'sine bağlıdır; Not Linked to You diyebilirsiniz. Emin değilseniz Linked to You seçin.
• Tracking. Uygulamanız §7.6'da anlatılan anlamda tracking yapmıyorsa Not used to track you.
• Gizlilik manifesti. Apple bazı API'ler için hem sizin kodunuzda hem de her plugin'de bir kullanım gerekçesi ister. Bu entegrasyonda durum şöyle:
  • shared_preferences, ID'leri ve açık/kapalı ayarını UserDefaults'ta tutar. iOS plugin'i UserDefaults (NSPrivacyAccessedAPICategoryUserDefaults) kullanımını beyan eden kendi gizlilik manifestiyle gelir; tracker için ayrıca girdi eklemeniz gerekmez.
  • Kuyruk dosyası dart:io ile yazılır; Flutter engine kullandığı dosya API'leri için kendi gizlilik manifestiyle gelir.
  • device_info_plus (13.3.0), tracker işletim sistemi sürümünü ve modeli isterken device'ın boş disk alanını da okur. Tracker bu değeri kullanmaz, plugin'in manifesti de bunun için gerekçe beyan etmez. Yüklemeden sonra App Store Connect NSPrivacyAccessedAPICategoryDiskSpace için eksik gerekçe uyarısı verirse (ITMS-91053), bu kategoriyi Apple'ın listesinden uygulamanıza uyan bir gerekçeyle PrivacyInfo.xcprivacy dosyanıza ekleyin ya da plugin'in geliştiricilerine sorun.
  • Sizin kontrol etmeniz gerekenler: uygulamanızın kendi PrivacyInfo.xcprivacy dosyası (Flutter bunu oluşturmaz; Xcode'da Runner target'ına ekleyin) etiketinizle uyuşan toplanan veri türlerini listelemeli. App Store Connect'in her yüklemeden sonra gönderdiği e-posta da diğer plugin'ler dahil bütün uygulamadaki eksik gerekçeleri listeler.

Apple'ın tanımları: App privacy details on the App Store ve Privacy manifest files.

7.8 Çocuklara yönelik uygulamalar

Apple'ın App Review Guidelines kuralları (1.3 ve 5.1.4), Kids kategorisindeki uygulamalarda üçüncü taraf analitiğe izin vermez. Tek istisna, hizmetin çocuklar hakkında device bilgileri dahil hiçbir tanımlayıcı bilgi toplamadığı sınırlı durumlardır. App Store Operator kalıcı bir install ID'si, device modeli ve ülke bilgisi aldığı için Kids kategorisindeki bir uygulamaya eklemeyin. Çocuklara yönelik başka bir uygulamanız varsa, entegrasyondan önce size hangi kuralların uygulandığını (örneğin ABD'de COPPA veya GDPR'ın çocuk onayı kuralları) hukuk danışmanınızla kontrol edin.

8. Doğrulama ve sorun giderme

1. Uygulamayı iOS simülatöründe veya device'ta çalıştırın (flutter run), birkaç event tetikleyin, sonra uygulamayı arka plana alın (kuyruk bu sırada gönderilir).
2. Dashboard → uygulamanız → Events → Canlı'yı açın. Event'leriniz birkaç saniye içinde görünür.
3. Events → Katalog her event adını property anahtarlarıyla birlikte listeler. Adların ve anahtarların istediğiniz gibi olduğunu kontrol edin.

Android, web ve masaüstü build'leri hiçbir şey göndermez. Debug build'de konsola bir kez [EventTracker] iOS only: tracking is off on android (ya da hangi platformsa onun adı) yazılır.

Test build'leri. Her uygulamanın tek bir yazma anahtarı var; test build'leri de App Store build'leri de aynı anahtarı kullanır. Referans kod debug ve profile build'lerinden (flutter run) gelen event'leri debug olarak etiketler. Release build'lerin event'leri ise --dart-define=ASO_ENV=... ile verilen environment değerini (testflight veya app_store) taşır ya da hiç etiket taşımaz. Dashboard varsayılan olarak app_store event'lerini ve ortam bilgisi olmayanları gösterir. Testlerinizi görmek için ortam filtresini Tüm build'ler yapın. Define verilmeden alınan release build TestFlight'ı App Store'dan ayırt edemez; bu yüzden TestFlight test kullanıcılarınınkiler dahil event'leri App Store event'i sayılır (§5). curl testi ortam bilgisi göndermediği için varsayılan görünümde çıkar; anonymous_id değeri curl-test olan event'e bakın.

9. Kontrol listesi

Bütün maddeler doğruysa entegrasyon bitmiştir. Raporda her kod maddesi için dosyayı ve satırı yazın. Uymayan bir maddeyi gerekçesiyle uygulanamaz, canlı API gerektiren bir maddeyi beklemede olarak işaretleyin.

• path_provider, shared_preferences, package_info_plus ve device_info_plus pubspec.yaml'da var; izleme için başka bağımlılık eklenmedi.
• lib/event_tracker.dart §5'tekiyle aynı (yalnızca iOS kontrolü dahil), flutter analyze hata vermiyor ve uygulama iOS için build alıyor (flutter build ios --no-codesign).
• configure(writeKey: ...), main() içinde WidgetsFlutterBinding.ensureInitialized()'dan sonra ve runApp'ten önce, bu uygulamanın gerçek anahtarıyla bir kez çağrılıyor; projede hiçbir yerde YOUR_WRITE_KEY kalmadı.
• EventTracker.shared.flush() uygulama arka plana geçince çağrılıyor.
• app_opened açılışta (source: "cold") ve arka plandan her dönüşte (source: "warm") izleniyor.
• §6'daki event'lerden akışı bu uygulamada olan her biri, tablodaki property'lerle izleniyor. Her birini event → file:line diye raporlayın; atladığınız §6 event'lerini de nedenleriyle yazın.
• Satın alma event'leri, geri yüklemelerin de düştüğü purchaseStream gibi bir listener'da değil, satın alma akışının içinde (§5.2) izleniyor.
• Her event adı ^[A-Za-z0-9_.:-]{1,64}$ ile eşleşiyor ve §6'daki adlandırma kurallarına uyuyor; her property değeri String, int, double, bool veya null.
• Hiçbir track çağrısı ad, e-posta, telefon numarası, hassas konum, IDFA veya kullanıcının yazdığı metni göndermiyor.
• Uygulamada hesap sistemi varsa identify oturum açıldıktan sonra uygulamanın kendi kullanıcı ID'siyle, reset de oturum kapatıldıktan sonra çağrılıyor. Hesap sistemi yoksa ikisi de çağrılmıyor.
• Canlı API: §3'teki curl testi accepted: 1 döndürüyor ve uygulamayı çalıştırınca gelen event'ler Dashboard → Events → Canlı'da görünüyor.
• Geliştirici: yukarıdaki event ve property listesi geliştiriciye verildi. Geliştirici bunu §7'ye, App Store gizlilik etiketine, uygulamanın PrivacyInfo.xcprivacy dosyasına, gizlilik politikasına ve varsa onay şartına göre kontrol edecek; bir build'de --dart-define=ASO_ENV kullanılıp kullanılmayacağına (§5) da o karar verecek. Uygulama Kids kategorisinde değil.