iOS SDK

Το Kixo iOS SDK υποστηρίζει Swift 5.9+ και iOS 16+ για analytics, attribution, push, παρακολούθηση κύκλου ζωής και αναπαραγωγή συνεδριών. Η αναπαραγωγή συνεδριών χρησιμοποιεί διακόπτες καταγραφής σε επίπεδο project και συντηρητικές προεπιλογές για τα βαρύτερα pipelines· δεν απαιτεί ξεχωριστό ελάχιστο όριο για OS ή μοντέλο συσκευής πέρα από το deployment target iOS 16 του package. Διανέμεται μέσω Swift Package Manager και, με μία μόνο κλήση Kixo.configure, καταγράφει αυτόματα οθόνες, πατήματα, συνεδρίες, crashes, push notifications και συμβάντα κύκλου ζωής. Η παρακολούθηση αιτημάτων δικτύου είναι προαιρετική.

Εγκατάσταση

Swift Package Manager

Στο Xcode, ανοίξτε το File → Add Package Dependencies και εισαγάγετε:

https://github.com/kixoio/kixo-ios-sdk

Αν διαχειρίζεστε dependencies στο Package.swift, χρησιμοποιήστε το binary release package και το product:

dependencies: [
    .package(
        url: "https://github.com/kixoio/kixo-ios-sdk",
        from: "1.0.21"
    ),
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "Kixo", package: "kixo-ios-sdk"),
        ]
    )
]

Ρύθμιση

Αρχικοποιήστε το Kixo στο struct App του SwiftUI ή στο AppDelegate:

import Kixo

@main
struct MyApp: App {
    init() {
        Kixo.configure(
            projectId: "YOUR_PROJECT_ID",
            apiKey: "YOUR_API_KEY"
        )
    }

    var body: some Scene {
        WindowGroup { ContentView() }
    }
}

Επιλογές ρύθμισης

Kixo.configure(
    projectId: "YOUR_PROJECT_ID",
    apiKey: "YOUR_API_KEY",
    options: ConfigurationOptions(
        autoTrackScreens:   true,
        autoTrackTaps:      true,
        autoTrackNetwork:   false,
        autoTrackCrashes:   true,
        autoTrackSessions:  true,
        autoTrackPush:      true,
        sessionTimeout:     30,
        flushInterval:      30,
        flushAt:            20,
        maxBufferSize:      200,
        // apiHost:    nil  → managed Kixo ingest host
        // debug:      nil  → true in DEBUG, false otherwise
        // environment: nil → production
    )
)

Συμβάντα αυτόματης καταγραφής

• screen_view — άμεσες εμφανίσεις view controller του UIKit + πλοήγηση SwiftUI
• screen_visit — δομημένη επίσκεψη που κλείνει σε πλοήγηση ή όταν η εφαρμογή περάσει στο παρασκήνιο, με χρόνο παραμονής, μετρήσεις αλληλεπίδρασης, ταυτότητα οθόνης και μεταδεδομένα ροής
• session_start / session_end
• tap — πατήματα κουμπιών και recognizers χειρονομιών
• crash — διαγνωστικά στοιχεία από crashes και exceptions που καταγράφηκαν
• network — προαιρετικά καθαρισμένα συγκεντρωτικά στοιχεία αιτημάτων και διαγνωστικά διαδρομών
• push_received / push_open / push_dismissed / push_silent / push_action — πλήρης κύκλος ζωής των push
• push_permission / push_token_invalidated
• lifecycle — μεταβάσεις foreground / background / εκκίνησης εφαρμογής

Προσαρμοσμένα συμβάντα

Kixo.track("purchase_completed", properties: [
    "product_id": "SKU-123",
    "amount": 49.99,
    "currency": "USD",
])

Τυποποιημένα βοηθήματα για events

Συντακτική διευκόλυνση πάνω από το Kixo.track για τα events που το Kixo αναγνωρίζει ονομαστικά (purchase, signup,subscribe_start, trial_start,cancel, upgrade, activation,share, invite). Έλεγχος του σχήματος των properties κατά τη μεταγλώττιση και ενιαίο σημείο αναφοράς για τα ονόματα κλειδιών — ο ανιχνευτής standard events του backend κάνει ακριβή αντιστοίχιση.

Kixo.trackPurchase(
    amount: 49.99,
    currency: "USD",
    productId: "pro_yearly"
)

Kixo.trackSubscriptionStart(
    plan: "pro",
    amount: 9.99,
    currency: "USD",
    interval: .month
)

Kixo.trackSignup(method: "google")
Kixo.trackTrialStart(plan: "pro", days: 14)
Kixo.trackCancel(plan: "pro", reason: "too_expensive")
Kixo.trackUpgrade(fromPlan: "free", toPlan: "pro")
Kixo.trackActivation(event: "first_post_published")
Kixo.trackShare(channel: "twitter", contentId: "post_123")
Kixo.trackInvite(channel: "email", recipientCount: 5)

Ταυτοποίηση χρηστών

Τα δεσμευμένα κλειδιά τυπικών ιδιοτήτων έχουν πρόθεμα $ (σύμβαση Mixpanel), ώστε να ξεχωρίζουν από τα δικά σας προσαρμοσμένα traits και να προωθούνται στις στήλες προφίλ του dashboard. Χρησιμοποιήστε το τυποποιημένο enum StandardProperty ή την ακατέργαστη συμβολοσειρά με πρόθεμα $ — δείτε τον Τυπικός κατάλογος ιδιοτήτων παρακάτω για την πλήρη λίστα με τα 37 κλειδιά.

Kixo.identify("user_123", traits: [
    "$email": "jane@example.com",       // identity
    "$name":  "Jane Doe",                // identity
    "$plan":  "pro",                     // subscription pack
    "$lifetime_orders": 12,              // e-commerce pack
    "signup_source": "twitter_ad"       // custom trait
])

Προσθήκη ετικέτας σε χρήστη για τμηματοποίηση

Χρησιμοποιήστε το setUserProperty με τιμή boolean για να προσθέσετε στον χρήστη μια απλή ετικέτα ναι/όχι. Η ετικέτα παραμένει ενεργή σε όλες τις συνεδρίες και χρησιμοποιείται σε τμήματα κοινού, email καμπάνιες και ερωτήματα συνομιλίας — χωρίς καμία επιπλέον ρύθμιση πέρα από την κλήση του SDK.

// Tag a user as subscribed — segments + campaigns can target this
Kixo.setUserProperty("subscribe", value: true)

// VIP membership
Kixo.setUserProperty("vip", value: true)

// String + numeric values work too
Kixo.setUserProperty("plan_tier", value: "enterprise")
Kixo.setUserProperty("lifetime_orders", value: 42)

// Bulk-set
Kixo.setUserProperties([
    "subscribe": true,
    "plan_tier": "enterprise",
])

Οι ιδιότητες αποθηκεύονται στο UserDefaults, διατηρούνται ανάμεσα σε launches και προστίθενται αυτόματα σε κάθε εξερχόμενο event. Στο chat πείτε πράγματα όπως "στείλε email καλωσορίσματος στους χρήστες όπου το subscribe είναι true" — το Kixo δημιουργεί το segment και ετοιμάζει το template για εσάς. Καθαρίζονται στο Kixo.reset().

Τυπικός κατάλογος ιδιοτήτων

Τα δεσμευμένα κλειδιά ιδιοτήτων έχουν πρόθεμα $, ώστε να ξεχωρίζουν από τα δικά σας custom traits. Ο κατάλογος του Kixo καλύπτει 37 κλειδιά σε 3 οριζόντια πακέτα (identity, geo, lifecycle) και 5 κάθετα πακέτα για B2B (subscription, e-commerce, media, marketplace, loyalty). Ορίστε όσα ταιριάζουν στο προϊόν σας — το dashboard προσαρμόζεται και εμφανίζει μόνο τα πακέτα που έχετε συμπληρώσει.

Ταυτότητα

Πάντα σχετικό. Ορίζει τις στήλες στην κεφαλίδα του προφίλ.

Γεωγραφικά στοιχεία

Γεωγραφικό πλαίσιο.

Κύκλος ζωής

Πότε τον είδαμε.

Συνδρομή

Ορίστε το αν το προϊόν σας έχει συνδρομητικά πλάνα.

Ηλεκτρονικό εμπόριο

Ορίστε το αν πουλάτε προϊόντα.

Μέσα

Ορίστε το αν δημοσιεύετε περιεχόμενο.

Marketplace

Ορίστε το αν το προϊόν σας είναι πλατφόρμα δύο πλευρών.

Πιστότητα

Ορίστε το αν έχετε προγράμματα αφοσίωσης και επιβράβευσης.

Super-properties

Ζεύγη κλειδιού/τιμής ανά συνεδρία που προστίθενται αυτόματα σε κάθε εξερχόμενο event. Διαφέρουν από τα traits του identify (που περιγράφουν την ταυτότητα)· τα super-properties περιγράφουν το πλαίσιο της συνεδρίας — ενεργή παραλλαγή A/B, build flavor, ενεργά feature flags. Αποθηκεύονται στο UserDefaults και διατηρούνται ανάμεσα σε launches· καθαρίζονται στο reset(). Σε σύγκρουση, οι ιδιότητες ανά event στο track μέσω του properties υπερισχύουν πάντα.

Kixo.setSuperProperty("build_flavor", value: "beta")
Kixo.setSuperProperties([
    "ab_variant": "B",
    "referrer_campaign": "autumn-launch",
])

// Sugar for A/B tracking — keys as 'experiment_<id>'.
Kixo.setExperimentVariant("checkout_v2", variant: "variant_a")

Kixo.unsetSuperProperty("build_flavor")
Kixo.clearSuperProperties()

Καταγραφή οθονών στο SwiftUI

Οι προβολές οθόνης στο SwiftUI καταγράφονται αυτόματα όταν το SDK μπορεί να προσδιορίσει όνομα προβολής. Για πιο λεπτομερή έλεγχο ή προσαρμοσμένα ονόματα, χρησιμοποιήστε το view modifier .kixoScreen():

struct HomeView: View {
    var body: some View {
        VStack { Text("Welcome") }
            .kixoScreen("HomeView")
    }
}

Αναπαραγωγή συνεδρίας

Το Replay ανασυνθέτει αυτό που είδε πραγματικά ο χρήστης — το SDK καταγράφει καρέ οθόνης κωδικοποιημένα σε HEIC μαζί με ένα δομικό στιγμιότυπο της ιεραρχίας προβολών, και ο player του dashboard τα συνθέτει σε αναπαραγωγή με δυνατότητα μετακίνησης δίπλα στη χρονογραμμή συμβάντων. Ρυθμίστε το replay για το project στο Πίνακας ελέγχου → Ρυθμίσεις → Αναπαραγωγή συνεδρίας· το SDK διαβάζει αυτόματα αυτή την πολιτική και την ανανεώνει όσο εκτελείται η εφαρμογή.

Kixo.configure(
    projectId: "YOUR_PROJECT_ID",
    apiKey: "YOUR_API_KEY"
)

Το dashboard ελέγχει αν είναι ενεργό το replay, την απόκρυψη, τους τρόπους καταγραφής και το αν το native replay επιτρέπεται να ανεβάζει δεδομένα μέσω δικτύου κινητής. Όταν η αποστολή μέσω κινητού είναι απενεργοποιημένη, τα καρέ μπορούν παρ’ όλα αυτά να καταγράφονται σε έναν περιορισμένο buffer στη συσκευή· η αποστολή περιμένει μέχρι να βρεθεί επιτρεπόμενο δίκτυο.

Το SDK καταγράφει τα δεδομένα που έχετε ενεργοποιήσει στο project σας, καθώς και τα συμβάντα και τις ιδιότητες που στέλνει η εφαρμογή σας.

Απόκρυψη και ιδιωτικότητα

Επειδή το replay καταγράφει pixels, η απόκρυψη γίνεται στη συσκευή πριν κωδικοποιηθεί οποιοδήποτε καρέ. Τα πεδία κωδικού πρόσβασης και άλλα ευαίσθητα πεδία εντοπίζονται και αποκρύπτονται αυτόματα, ενώ το κείμενο που καταγράφεται στο δομικό στιγμιότυπο περνά από φίλτρο PII. Για να αποκρύψετε οτιδήποτε προσαρμοσμένο — ένα ιδιωτικό νήμα μηνυμάτων, ένα υπόλοιπο λογαριασμού, μια οθόνη προσχεδίου — ορίστε το kxRedact στο view. Το Kixo κάνει rasterize ένα συμπαγές ορθογώνιο πάνω στα όρια αυτού του view πριν από την κωδικοποίηση HEIC, ώστε τα pixels του να μην φύγουν ποτέ από τη συσκευή.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Ειδοποιήσεις push

Το SDK εγκαθιστά ένα AppDelegate proxy στο runtime στο Kixo.configure — τα silent pushes (content-available: 1) και τα ορατά push που παραδίδονται στο παρασκήνιο καταγράφονται αυτόματα. Δεν χρειάζεται να προσθέσετε κώδικα στο AppDelegate σας. Οι υπάρχουσες υλοποιήσεις του UNUserNotificationCenterDelegate συνεχίζουν να εκτελούνται κανονικά· το Kixo τις τυλίγει.

Καταχωρίστε το device token μέσω του standard didRegisterForRemoteNotificationsWithDeviceToken:

func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    let token = deviceToken.map { String(format: "%02x", $0) }.joined()
    Kixo.setPushToken(token)
}

Αν η εφαρμογή χρησιμοποιεί Firebase Messaging, περάστε το registration token με το provider: .firebase. Το Kixo αποθηκεύει αυτόν τον πάροχο και παραδίδει μέσω FCM HTTP v1· πριν στείλετε καμπάνιες, ρυθμίστε στο Kixo το Firebase service account της εφαρμογής.

func messaging(_ messaging: Messaging, didReceiveRegistrationToken token: String?) {
    guard let token else { return }
    Kixo.setPushToken(token, provider: .firebase)
}

Παράδοση και συμπεριφορά εκτός σύνδεσης

Το SDK βάζει τα events σε τοπική ουρά, τα στέλνει σε παρτίδες και επαναλαμβάνει τις προσωρινές αποτυχίες με backoff. Αν η συλλογή παγώσει από τις ρυθμίσεις του project, τα νέα events δεν αποστέλλονται μέχρι να ενεργοποιηθεί ξανά.

Διαγνωστικά

Στιγμιότυπο κατάστασης μόνο για ανάγνωση. Χρήσιμο σε debug screens ή smoke tests — απαντά στο «γιατί δεν φτάνουν τα events μου;» χωρίς debugger.

let diag = Kixo.diagnostics()
print(diag.queue.bufferedEventCount)  // events waiting to flush
print(diag.paused)                     // collection paused state
print(diag.environment)                // configured environment
print(diag.apiHost)                    // configured ingest host

Υποχρεωτική αποστολή (για tests)

Σύγχρονη υπερφόρτωση που μπλοκάρει έως timeout δευτερόλεπτα μέχρι να ολοκληρωθεί ένα flush. Προορίζεται για fixtures του XCTest — μην την καλείτε ποτέ από το main thread.

func testEventLanded() {
    Kixo.track("test_event")
    let landed = Kixo.flush(timeout: 5.0)
    XCTAssertTrue(landed)
}

Επαναφορά

Καθαρίζει την ταυτότητα, τα super-properties και την αποθηκευμένη ουρά. Καλέστε το στο logout, ώστε τα επόμενα events να μην αποδοθούν στον προηγούμενο χρήστη.

Kixo.reset()