iOS SDK (Swift)

The Datafly Signal iOS SDK is a native Swift package that captures events on-device and delivers them to your Signal pipeline. It has zero external dependencies and uses only Apple framework APIs.

Requirements

iOS 15.0+, tvOS 15.0+, or macOS 12.0+
Swift 5.9+
Xcode 15+

Installation

Swift Package Manager (recommended)

Add the Datafly Signal package to your Xcode project:

In Xcode, go to File > Add Package Dependencies

Enter the repository URL:

https://github.com/wearedatafly/datafly-signal-ios

Select the DataflySignal library and add it to your target

Or add it to your Package.swift:

dependencies: [
    .package(url: "https://github.com/wearedatafly/datafly-signal-ios", from: "1.0.0")
]

CocoaPods

pod 'DataflySignal', '~> 1.0'

Initialisation

Initialise the SDK as early as possible in your app lifecycle, typically in your AppDelegate or @main App struct:

import DataflySignal
 
@main
struct MyApp: App {
    init() {
        let config = DataflyConfig(
            pipelineKey: "dk_live_abc123",
            endpoint: "https://data.example.com"
        )
        Datafly.shared.initialize(config: config)
    }
 
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

UIKit

import DataflySignal
 
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        let config = DataflyConfig(
            pipelineKey: "dk_live_abc123",
            endpoint: "https://data.example.com"
        )
        Datafly.shared.initialize(config: config)
        return true
    }
}

Quick start

// Track a screen view
Datafly.shared.screen("Home")
 
// Track a custom event
Datafly.shared.track("add_to_cart", properties: [
    "item_id": "SKU-001",
    "item_name": "Running Shoes",
    "price": 79.99,
    "currency": "GBP"
])
 
// Identify a user after login
Datafly.shared.identify(userId: "user-123", traits: [
    "email": "[email protected]",
    "name": "Jane Doe",
    "plan": "professional"
])
 
// Associate with a company
Datafly.shared.group(groupId: "company-456", traits: [
    "name": "Acme Corp",
    "plan": "enterprise"
])
 
// Handle a deep link (extracts UTM params and click IDs)
Datafly.shared.handleDeepLink(url: incomingURL)
 
// Set IDFA after ATT consent
import AppTrackingTransparency
 
ATTrackingManager.requestTrackingAuthorization { status in
    if status == .authorized {
        let idfa = ASIdentifierManager.shared().advertisingIdentifier.uuidString
        Datafly.shared.setAdvertisingId(idfa, enabled: true)
    }
}
 
// Force flush (e.g., before app termination)
Datafly.shared.flush()
 
// Logout -- generates new anonymous ID
Datafly.shared.reset()

Device identifiers

The iOS SDK automatically collects:

Identifier	Source	Persistence	Permission required
Anonymous ID	UUID v4, SDK-generated	Keychain (survives reinstall)	None
IDFV	`UIDevice.identifierForVendor`	System-managed	None
Device model	`hw.machine` via `sysctlbyname`	N/A	None
IDFA	Set via `setAdvertisingId()`	Memory	ATT consent

The anonymous ID is stored in the iOS Keychain with kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly accessibility. This means it persists across app reinstalls and device restarts, providing stronger identity continuity than UserDefaults alone.

App lifecycle events

When trackAppLifecycle is enabled (default), the SDK automatically tracks:

Event	When	Properties
`Application Installed`	First launch after install	`version`, `build`
`Application Updated`	First launch after app update	`version`, `build`, `previous_version`, `previous_build`
`Application Opened`	App enters foreground	`version`, `build`, `from_background`
`Application Backgrounded`	App enters background	—

Configuration reference

Property	Type	Default	Description
`pipelineKey`	`String`	Required	Your source pipeline key
`endpoint`	`String`	Required	Your Ingestion Gateway URL
`flushInterval`	`TimeInterval`	`30`	Seconds between automatic flushes
`flushThreshold`	`Int`	`20`	Events queued before automatic flush
`maxQueueSize`	`Int`	`1000`	Maximum events stored locally
`sessionTimeout`	`TimeInterval`	`1800`	Seconds of inactivity before new session (30 min)
`trackAppLifecycle`	`Bool`	`true`	Automatically track install/update/open/background
`debug`	`Bool`	`false`	Enable debug logging to console

Debug mode

Enable debug logging to see all SDK activity in the Xcode console:

let config = DataflyConfig(
    pipelineKey: "dk_live_abc123",
    endpoint: "https://data.example.com",
    debug: true
)

You can also attach an event inspector callback:

Datafly.shared.onEvent = { eventJSON in
    print("Event queued: \(eventJSON)")
}

Next steps

track() — record custom events
screen() — record screen views
identify() — link anonymous users to known identities
Identity & Device IDs — understand how identity works on iOS
Offline & Batching — how events are queued and delivered

Overview Android (Kotlin)