iOS (Swift) 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: Native bir Swift uygulamasına (SwiftUI veya UIKit) event takibi ekleyen iOS 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.

---

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

Bir iOS uygulamasına event takibi ekliyorsunuz. Uygulamanın sahibi bu event'lerle App Store Operator'da funnel'lar oluşturacak. Uygulama event'leri X-Write-Key header'ıyla POST https://api.app-store-operator.com/v1/events adresine gönderecek.

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 dosyayı hiç değiştirmeden, EventTracker.swift adıyla ana uygulama target'ına kopyalayın. Extension'lara (widget, share, notification extension'ları) eklemeyin.
3. Uygulamaya bağlayın (§5.1). Açılışta bir kez configure(writeKey:) çağırın. Uygulama arka plana geçince EventTracker.flushInBackground() çağırın. Açılışta ve arka plandan her dönüşte app_opened event'ini 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

• EventTracker.swift'in davranışını (batch'leme, retry, endpoint, kuyruk) değiştirmeyin. Uygulamaya uymuyorsa dosyayı yeniden yazmayın, nedenini raporlayın.
• Üçüncü taraf bağımlılık eklemeyin.
• 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, sayı veya boolean. İç içe nesne veya dizi göndermeyin (§4.3).
• §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 veya Info.plist'te 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 dosya, bağımlılık yok, iOS 15+. Swift 5 ve Swift 6 dil modlarında derlenir. Ana uygulama target'ına EventTracker.swift olarak ekleyin ve hiç değiştirmeden kullanın.

Dosya şunları yapar:

• İlk event izlendiğinde rastgele bir anonim ID üretir ve UserDefaults'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 kuyruğa 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'lerde, reddedilen ve clamp'lenen event'leri ve atılan batch'leri Xcode konsoluna [EventTracker] … diye yazar. Release build'ler konsola hiçbir şey yazmaz.
• Her event'i debug, testflight veya app_store olarak etiketler (StoreKit, iOS 16+). Böylece testleriniz funnel'larınıza karışmaz.
• flushInBackground() iOS'tan ek süre ister; uygulama askıya alınırken son event'ler de gönderilir.

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. 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 ana uygulamadan izleyin.

import Foundation
import StoreKit
#if canImport(UIKit)
import UIKit
#endif

/// Event'leri App Store Operator'a gönderir. Belgeler: https://app-store-operator.com/docs/events/ios
public actor EventTracker {
    public static let shared = EventTracker()

    public enum Value: Codable, Sendable, ExpressibleByStringLiteral, ExpressibleByIntegerLiteral,
        ExpressibleByFloatLiteral, ExpressibleByBooleanLiteral {
        case string(String), int(Int), double(Double), bool(Bool)

        public init(stringLiteral value: String) { self = .string(value) }
        public init(integerLiteral value: Int) { self = .int(value) }
        public init(floatLiteral value: Double) { self = .double(value) }
        public init(booleanLiteral value: Bool) { self = .bool(value) }

        public init(from decoder: Decoder) throws {
            let c = try decoder.singleValueContainer()
            if let v = try? c.decode(Bool.self) { self = .bool(v) }
            else if let v = try? c.decode(Int.self) { self = .int(v) }
            else if let v = try? c.decode(Double.self) { self = .double(v) }
            else { self = .string(try c.decode(String.self)) }
        }

        public func encode(to encoder: Encoder) throws {
            var c = encoder.singleValueContainer()
            switch self {
            case .string(let v): try c.encode(v)
            case .int(let v): try c.encode(v)
            case .double(let v): try c.encode(v)
            case .bool(let v): try c.encode(v)
            }
        }
    }

    private struct Context: Codable, Sendable {
        let appVersion, build, osVersion, deviceModel, locale: String
        var environment: String?
        enum CodingKeys: String, CodingKey {
            case appVersion = "app_version", build, osVersion = "os_version",
                 deviceModel = "device_model", locale, environment
        }
    }

    private struct Event: Codable, Sendable {
        let eventId, name, anonymousId: String
        let userId: String?
        let occurredAt: String
        let properties: [String: Value]
        var context: Context
        enum CodingKeys: String, CodingKey {
            case eventId = "event_id", name, anonymousId = "anonymous_id", userId = "user_id",
                 occurredAt = "occurred_at", properties, context
        }
    }

    private struct Batch: Encodable { let events: [Event] }

    private let endpoint = URL(string: "https://api.app-store-operator.com/v1/events")!
    private let maxBatch = 100
    private let maxQueue = 1_000
    private let flushAt = 20
    private let anonymousIdKey = "aso.events.anonymousId"
    private let userIdKey = "aso.events.userId"
    private let disabledKey = "aso.events.disabled"
    private let storeURL: URL
    private let context: Context
    private let timestamp: ISO8601DateFormatter

    private var writeKey: String?
    private var anonymousId: String?
    private var isEnabled: Bool
    private var userId: String?
    private var queue: [Event]
    private var isFlushing = false
    private var timer: Task<Void, Never>?
    private var retryAt: Date?
    private var backoff: TimeInterval = 0
    private var environment: String?

    private init() {
        let defaults = UserDefaults.standard
        isEnabled = !defaults.bool(forKey: disabledKey)
        anonymousId = defaults.string(forKey: anonymousIdKey) // ilk izlenen event'le oluşturulur
        userId = defaults.string(forKey: userIdKey)

        let dir = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
        try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
        storeURL = dir.appendingPathComponent("aso-events-queue.json")
        queue = (try? JSONDecoder().decode([Event].self, from: Data(contentsOf: storeURL))) ?? []

        let info = Bundle.main.infoDictionary ?? [:]
        let os = ProcessInfo.processInfo.operatingSystemVersion
        var system = utsname()
        uname(&system)
        let model = withUnsafeBytes(of: &system.machine) { raw in
            String(decoding: raw.prefix { $0 != 0 }, as: UTF8.self)
        }
        context = Context(
            appVersion: info["CFBundleShortVersionString"] as? String ?? "",
            build: info["CFBundleVersion"] as? String ?? "",
            osVersion: "\(os.majorVersion).\(os.minorVersion).\(os.patchVersion)",
            deviceModel: model,
            locale: Locale.current.identifier,
            environment: nil // gönderim sırasında doldurulur, bkz. resolveEnvironment()
        )

        timestamp = ISO8601DateFormatter()
        timestamp.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
    }

    /// Açılışta bir kez çağırın.
    public func configure(writeKey: String) {
        self.writeKey = writeKey
        guard timer == nil else { return }
        timer = Task {
            while !Task.isCancelled {
                try? await Task.sleep(nanoseconds: 30_000_000_000)
                await self.flush()
            }
        }
    }

    /// Bu install'ın kimliği; ilk izlenen event'ten önce ve izleme kapalıyken nil.
    /// Kullanıcının verilerinin silinmesini isteyebilmesi için bir destek ekranında gösterin.
    public var currentAnonymousId: String? { 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.
    public func setEnabled(_ enabled: Bool) {
        isEnabled = enabled
        let defaults = UserDefaults.standard
        defaults.set(!enabled, forKey: disabledKey)
        guard !enabled else { return }
        anonymousId = nil
        userId = nil
        queue.removeAll()
        defaults.removeObject(forKey: anonymousIdKey)
        defaults.removeObject(forKey: userIdKey)
        try? FileManager.default.removeItem(at: storeURL)
    }

    /// Bir event'i kaydeder. Hafiftir; ağ için asla beklemez. İzleme kapalıyken hiçbir şey yapmaz.
    public func track(_ name: String, _ properties: [String: Value] = [:]) {
        guard isEnabled else { return }
        let anonymousId = anonymousId ?? newAnonymousId()
        queue.append(Event(
            eventId: UUID().uuidString,
            name: name,
            anonymousId: anonymousId,
            userId: userId,
            occurredAt: timestamp.string(from: Date()),
            properties: properties,
            context: context
        ))
        if queue.count > maxQueue { queue.removeFirst(queue.count - maxQueue) }
        persist()
        if queue.count >= flushAt { Task { await self.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.
    public func identify(userId: String) {
        guard isEnabled else { return }
        self.userId = userId
        UserDefaults.standard.set(userId, forKey: userIdKey)
    }

    /// Oturum kapatılırken çağırın: sonraki event'ler yeni bir anonim kişiye ait olur.
    public func reset() {
        userId = nil
        anonymousId = nil
        UserDefaults.standard.removeObject(forKey: userIdKey)
        UserDefaults.standard.removeObject(forKey: anonymousIdKey)
    }

    private func newAnonymousId() -> String {
        let id = UUID().uuidString
        anonymousId = id
        UserDefaults.standard.set(id, forKey: anonymousIdKey)
        return id
    }

    /// Kuyruktaki event'leri gönderir. Bir yeniden deneme beklemesi sürerken hiçbir şey yapmaz.
    public func flush() async {
        guard isEnabled, !isFlushing, let writeKey, !queue.isEmpty else { return }
        if let retryAt, retryAt > Date() { return }
        isFlushing = true
        defer { isFlushing = false }
        let environment = await resolveEnvironment()

        while !queue.isEmpty {
            var batch = Array(queue.prefix(maxBatch))
            for i in batch.indices where batch[i].context.environment == nil {
                batch[i].context.environment = environment
            }
            var request = URLRequest(url: endpoint)
            request.httpMethod = "POST"
            request.setValue("application/json", forHTTPHeaderField: "Content-Type")
            request.setValue(writeKey, forHTTPHeaderField: "X-Write-Key")
            request.httpBody = try? JSONEncoder().encode(Batch(events: batch))

            guard let (data, response) = try? await URLSession.shared.data(for: request) else {
                delayRetry(nil) // çevrimdışı: kuyruğu tut
                return
            }
            guard isEnabled else { return } // gönderim sırasında kapatıldı: kuyruk zaten silindi
            let http = response as? HTTPURLResponse
            let status = http?.statusCode ?? 0
            if status == 429 || status >= 500 {
                let retryAfter = http?.value(forHTTPHeaderField: "Retry-After").flatMap(TimeInterval.init)
                delayRetry(status == 429 ? retryAfter : nil) // kuyruğu tut
                return
            }
            retryAt = nil
            backoff = 0
            #if DEBUG
            report(status: status, body: data)
            #endif
            // 2xx: saklandı. Diğer 4xx: aynı batch'i tekrar denemenin anlamı yok.
            let sent = Set(batch.map(\.eventId))
            queue.removeAll { sent.contains($0.eventId) }
            persist()
        }
    }

    /// Sunucu belirtirse `seconds` kadar, aksi hâlde 30 sn, 60 sn, 120 sn… en fazla 10 dakika bekler.
    private func delayRetry(_ seconds: TimeInterval?) {
        backoff = min(max(backoff * 2, 30), 600)
        retryAt = Date().addingTimeInterval(seconds ?? backoff)
    }

    private func persist() {
        try? JSONEncoder().encode(queue).write(to: storeURL, options: .atomic)
    }

    #if DEBUG
    /// Yalnızca Debug build'lerde: atılan batch'leri ve reddedilen veya clamp'lenen event'leri Xcode konsoluna yazdırır.
    private func report(status: Int, body: Data) {
        let json = (try? JSONSerialization.jsonObject(with: body)) as? [String: Any] ?? [:]
        guard (200..<300).contains(status) else {
            print("[EventTracker] HTTP \(status), batch dropped: \(json)")
            return
        }
        for key in ["rejected", "clamped"] {
            if let items = json[key] as? [Any], !items.isEmpty { print("[EventTracker] \(key): \(items)") }
        }
    }
    #endif

    /// "debug", "testflight" veya "app_store". Release build'ler StoreKit'e sorar (iOS 16+); iOS 15'te bilinmez kalır.
    private func resolveEnvironment() async -> String? {
        if let environment { return environment }
        #if DEBUG
        environment = "debug"
        #else
        if #available(iOS 16.0, macOS 13.0, *), let result = try? await AppTransaction.shared {
            switch result.unsafePayloadValue.environment {
            case .production: environment = "app_store"
            case .sandbox: environment = "testflight"
            case .xcode: environment = "debug"
            default: break
            }
        }
        #endif
        return environment
    }
}

#if canImport(UIKit)
extension EventTracker {
    /// Uygulama arka plana geçtiğinde kuyruğu gönderir; bitirebilmek için iOS'tan süre ister.
    @MainActor public static func flushInBackground() {
        let task = BackgroundTask()
        Task {
            await shared.flush()
            task.end()
        }
    }
}

@MainActor private final class BackgroundTask {
    private var id = UIBackgroundTaskIdentifier.invalid

    init() {
        id = UIApplication.shared.beginBackgroundTask { [weak self] in self?.end() }
    }

    func end() {
        guard id != .invalid else { return }
        UIApplication.shared.endBackgroundTask(id)
        id = .invalid
    }
}
#endif

5.1 Uygulamaya bağlama

import SwiftUI

@main
struct MyApp: App {
    @Environment(\.scenePhase) private var scenePhase
    @State private var wasInBackground = false

    init() {
        Task {
            await EventTracker.shared.configure(writeKey: "YOUR_WRITE_KEY")
            await EventTracker.shared.track("app_opened", ["source": "cold"])
        }
    }

    var body: some Scene {
        WindowGroup { ContentView() }
            .onChange(of: scenePhase) { _, phase in // iOS 17+; iOS 15–16'da `{ phase in }` kullanın
                switch phase {
                case .background:
                    wasInBackground = true
                    EventTracker.flushInBackground()
                case .active where wasInBackground:
                    wasInBackground = false
                    Task { await EventTracker.shared.track("app_opened", ["source": "warm"]) }
                default:
                    break
                }
            }
    }
}

UIKit: application(_:didFinishLaunchingWithOptions:)'ta, yukarıdaki gibi bir Task { … } içinde configure'ı çağırın ve app_opened event'ini source: "cold" ile izleyin. sceneDidEnterBackground(_:)'da (scene kullanmıyorsanız applicationDidEnterBackground(_:)'da) EventTracker.flushInBackground() çağırın. sceneWillEnterForeground(_:)'da (ya da applicationWillEnterForeground(_:)'da) app_opened event'ini source: "warm" ile izleyin.

app_opened her .active geçişinde değil, yalnızca arka plandan dönüşte gönderilir. Çünkü sistem uyarıları, Denetim Merkezi ve Face ID de uygulamayı önce inactive, sonra tekrar active yapar.

5.2 Event takibi

await EventTracker.shared.track("paywall_viewed", ["placement": "onboarding"])

// Senkron koddan (buton action'ları, delegate'ler):
Task { await EventTracker.shared.track("onboarding_completed", ["duration_s": 42]) }

// Uygulamanızda oturum açıldıktan / kapatıldıktan sonra:
await EventTracker.shared.identify(userId: 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 nil).
let 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.

Literal değerler ("onboarding", 42, 39.99, true) property değerine kendiliğinden dönüşür. Değişkenleri ise sarmalamanız gerekir: .string(name), .int(count), .double(amount), .bool(flag).

StoreKit 2 ile satın almalar. Satın almaları, kullanıcının satın al butonuna bastığı akışın içinde izleyin. Transaction.updates'te izlemeyin; oraya yenilemeler ve başka device'lardan yapılan satın almalar da düşer.

import StoreKit

func buy(_ product: Product, startsTrial: Bool) async {
    let base: [String: EventTracker.Value] = ["product_id": .string(product.id)]
    await EventTracker.shared.track("purchase_started", base)
    do {
        switch try await product.purchase() {
        case .success(.verified):
            await EventTracker.shared.track("purchase_completed", base.merging([
                "price": .double(NSDecimalNumber(decimal: product.price).doubleValue),
                "currency": .string(product.priceFormatStyle.currencyCode),
                "trial": .bool(startsTrial),
            ]) { $1 })
            if startsTrial { await EventTracker.shared.track("trial_started", base) }
        case .userCancelled:
            await EventTracker.shared.track("purchase_failed", base.merging(["reason": "cancelled"]) { $1 })
        case .success(.unverified):
            await EventTracker.shared.track("purchase_failed", base.merging(["reason": "failed"]) { $1 })
        case .pending:
            break // Ask to Buy veya ek onay: henüz tamamlanmadı, hiçbir şey izlemeyin
        @unknown default:
            break
        }
    } catch {
        await EventTracker.shared.track("purchase_failed", base.merging(["reason": "failed"]) { $1 })
    }
}

startsTrial paywall'unuzun zaten bildiği bir değer: bu satın alma ücretsiz trial başlatıyorsa true. Uygulama satın almayı RevenueCat veya başka bir kütüphaneyle yapıyorsa aynı çağrıları o kütüphanenin satın alma metodunun etrafına koyun.

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).

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 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. Referans kod UserDefaults'a okuyup yazar; Apple bu API için kullanım gerekçesi ister. Uygulamanızın PrivacyInfo.xcprivacy dosyasında NSPrivacyAccessedAPICategoryUserDefaults girdisi CA92.1 gerekçesiyle yer almalı (çoğu uygulamada zaten vardır). Dosyadaki toplanan veri türleri de etiketinizle uyuşmalı.

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ı çalıştırın, 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.

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 her event'i debug, testflight veya app_store olarak etiketler. 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. iOS 15'te Release build'ler TestFlight'ı App Store'dan ayırt edemez, bu yüzden bu build'lerin event'leri App Store event'i sayılır. 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.

• EventTracker.swift yalnızca ana uygulama target'ında (extension'larda değil) ve §5'teki hâliyle duruyor; uygulama derleniyor.
• configure(writeKey:) açılışta, bu uygulamanın gerçek anahtarıyla bir kez çağrılıyor; projede hiçbir yerde YOUR_WRITE_KEY kalmadı.
• EventTracker.flushInBackground() 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 Transaction.updates'te değil, satın alma akışının içinde izleniyor.
• Her event adı ^[A-Za-z0-9_.:-]{1,64}$ ile eşleşiyor ve §6'daki adlandırma kurallarına uyuyor.
• 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, PrivacyInfo.xcprivacy'deki UserDefaults girdisine, uygulamanın gizlilik politikasına ve varsa onay şartına göre kontrol edecek. Uygulama Kids kategorisinde değil.