Cerezgo iOS SDK

Cerezgo, mobil uygulamalar için KVKK ve GDPR uyumlu, modern bir çerez onay (consent) ve analitik yönetim SDK'sıdır.

🚀 Başlarken

Cerezgo SDK, uygulamanızda kullanıcıların çerez tercihlerini yönetmenizi sağlar ve bu tercihlere göre analitik verilerin toplanmasını otomatik olarak denetler.

Gereksinimler

• iOS 14.0+
• Swift 5.9+
• Xcode 15.0+

---

📦 Kurulum

Swift Package Manager (SPM)

Xcode UI ile Kurulum

1. Xcode projenizde File > Add Packages... yolunu izleyin.
2. Repository URL olarak https://github.com/cerezgo/CerezgoiOSSDK adresini girin.
3. Dependency Rule olarak Up to Next Major Version seçin ve sürüm olarak 1.0.2 girin.
4. CerezgoSDK kütüphanesini hedef uygulamanıza ekleyin.

Package.swift ile Kurulum

Mevcut bir Swift paketi içerisine eklemek için Package.swift dosyanıza aşağıdaki satırları ekleyin:

dependencies: [
    .package(url: "https://github.com/cerezgo/CerezgoiOSSDK.git", from: "1.0.2")
],
targets: [
    .target(
        name: "MyTarget",
        dependencies: [
            .product(name: "CerezgoSDK", package: "CerezgoSDK")
        ]
    )
]

---

🛠 Kullanım

1. SDK'yı Başlatma

Uygulamanızın açılışında (AppDelegate veya SwiftUI App init) SDK'yı API anahtarınızla başlatın:

import CerezgoSDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Cerezgo.shared.initialize(apiKey: "SİZİN_API_ANAHTARINIZ")
        return true
    }
}

2. Consent (Onay) Kontrolü

SDK, başlatıldığında otomatik olarak consent durumunu kontrol eder. Ancak manuel olarak kontrol etmek veya bir butona bağlamak isterseniz:

SwiftUI

.onAppear {
    Task {
        // App açılışında consent banner gerekiyorsa gösterir
        try? await Cerezgo.shared.checkConsent(force: false)
    }
}

UIKit (SceneDelegate)

func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
    Task {
        // App açılışında consent banner gerekiyorsa gösterir
        try? await Cerezgo.shared.checkConsent(force: false)
    }
}

3. Analitik Event Takibi (Track Event)

Cerezgo, kullanıcının consent durumuna duyarlıdır. Eğer kullanıcı ilgili kategoride (örn. Pazarlama) izin vermemişse, event'ler dış sağlayıcılara iletilmez.

// Basit event
Cerezgo.shared.analytics.track(event: "button_clicked")

// Parametreli event
Cerezgo.shared.analytics.track(
    event: "purchase", 
    parameters: [
        "item_id": "123",
        "value": 99.90,
        "currency": "TRY"
    ]
)

// E-ticaret Satın Alma Takibi
Cerezgo.shared.analytics.trackPurchase(
    transactionId: "order_123",
    value: 1499.90,
    currency: "TRY",
    items: [
        ["id": "sku_1", "name": "Rider Jacket", "quantity": 1]
    ]
)

4. Kullanıcı Kimlik ve Özellikleri

// Kullanıcı ID atama
Cerezgo.shared.analytics.setUserId("user_123")

// Tekli kullanıcı özelliği
Cerezgo.shared.analytics.setUserProperty(name: "membership", value: "gold")

// Çoklu kullanıcı özelliği (Dictionary)
Cerezgo.shared.analytics.setUserProperties([
    "preferred_language": "tr",
    "customer_segment": "high_value"
])

// Kullanıcı verilerini temizleme (Logout vb. durumlarda)
Cerezgo.shared.analytics.clearUserData()

5. Consent Durumunu İzleme

// Herhangi bir rıza verilmiş mi?
let isCollected = Cerezgo.shared.analytics.hasConsent()

// Belirli bir kategoride izin var mı?
let hasAnalytics = Cerezgo.shared.analytics.isConsentGranted(category: .analytics)
let hasMarketing = Cerezgo.shared.analytics.isConsentGranted(category: .marketing)

// Tüm rıza verilerini temizle (Test amaçlı veya GDPR hakkı)
Cerezgo.shared.analytics.resetConsent()

---

🔒 Güvenlik ve API Anahtarı Doğrulaması

Cerezgo SDK, API anahtarınızın geçerliliğini backend üzerinden otomatik olarak doğrular.

SDK Durumları (SDKState)

SDK'nın o anki durumunu Cerezgo.shared.state üzerinden takip edebilirsiniz:

• .uninitialized: SDK henüz başlatılmadı.
• .active: SDK çalışıyor ve istek yapabiliyor.
• .invalidKey: Sağlanan API anahtarı backend tarafından reddedildi.

Lockdown (Kilitleme) Mekanizması

Eğer geçersiz bir API anahtarı tespit edilirse (HTTP 401/403):

1. SDK durumu .invalidKey olarak güncellenir.
2. Tüm analitik takibi (track çağrıları) durdurulur.
3. Arka plan ağ istekleri ve zamanlayıcılar kapatılır.
4. Kayıtlı tüm 3. taraf sağlayıcılar devre dışı bırakılır.

---

🤖 AI Asistanı ile Entegrasyon (Claude, Gemini, Copilot)

CerezgoSDK, AI asistanlarının (Cursor, Windsurf, GitHub Copilot, Claude vb.) kütüphaneyi hatasız bir şekilde projenize entegre edebilmesi için özel talimat dosyalarıyla birlikte gelir.

Entegrasyon sırasında asistanınıza aşağıdaki gibi bir komut vererek süreci hızlandırabilirsiniz:

"CerezgoSDK'yı projeme entegre etmeme yardımcı ol. Kütüphane içerisindeki .instructions/SDK_INTEGRATION.md dosyasını referans alarak kurulum, başlatma ve analitik izleme adımlarını uygula."

Desteklenen AI Prompt Dosyaları:

• .instructions/SDK_INTEGRATION.md: Genel entegrasyon rehberi (Tavsiye edilen).
• CLAUDE.md: Claude Code için özel talimatlar.
• .gemini/GEMINI.md: Google Gemini için yapılandırılmış veriler.
• .github/copilot-instructions.md: GitHub Copilot için bağlam dosyası.

---

📂 Örnek Projeler

SDK'nın nasıl entegre edileceğini gösteren iki bağımsız örnek uygulama Examples/ dizininde bulunmaktadır:

SwiftUI Example

Examples/CerezgoSwiftUIExample — Modern SwiftUI test konsolu.

UIKit Example

Examples/CerezgoUIKitExample — Pure UIKit, Storyboard-free uygulama.

---

📝 Lisans

Cerezgo iOS SDK, Nesil Grup Teknoloji Ticaret A.Ş. tarafından geliştirilmiştir. Tüm hakları saklıdır.