iOS SDK

Installation

Add the Trace SDK via Swift Package Manager in Xcode:

https://github.com/bmcreations/trace-ios

Or add to your Package.swift:

dependencies: [
    .package(url: "https://github.com/bmcreations/trace-ios", from: "<version>")
]

Initialization

Initialize Trace at app launch:

@main
struct MyApp: App {
    init() {
        TraceClient.shared.initialize(
            config: TraceConfig(
                apiKey: "tr_live_xxxxxxxxxxxx",
                hashSalt: "your_64_char_hex_salt"
            )
        )
    }

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

The SDK automatically performs attribution on first launch.

Handling deep links

Basic listener

TraceClient.shared.setDeepLinkListener { deepLink in
    // deepLink.path — e.g. "/product/123"
    // deepLink.params — e.g. ["color": "blue"]
    // deepLink.isDeferred — true if delivered via install attribution
    navigateTo(deepLink.path)
}

Universal Links

To handle direct deep links when the app is already installed, implement Universal Link handling:

@main
struct MyApp: App {
    init() {
        TraceClient.shared.initialize(config: /* ... */)
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
                .onOpenURL { url in
                    TraceClient.shared.handleUniversalLink(url)
                }
        }
    }
}

For UIKit apps using SceneDelegate:

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    guard let url = userActivity.webpageURL else { return }
    TraceClient.shared.handleUniversalLink(url)
}

SwiftUI deep link routing

Define route mappings and handle deep links in your navigation:

struct ContentView: View {
    @State private var path = NavigationPath()

    var body: some View {
        NavigationStack(path: $path) {
            HomeView()
                .navigationDestination(for: ProductRoute.self) { route in
                    ProductView(id: route.id)
                }
                .navigationDestination(for: InviteRoute.self) { route in
                    InviteView(code: route.code)
                }
        }
        .task {
            TraceClient.shared.setDeepLinkListener { deepLink in
                if let route = mapDeepLink(deepLink) {
                    path.append(route)
                }
            }
        }
    }
}

Attribution listener

React to the attribution result for analytics:

TraceClient.shared.setAttributionListener { result in
    switch result {
    case .attributed(let method, let campaignId, _):
        Analytics.track("install_attributed", properties: [
            "method": method,
            "campaign": campaignId ?? "unknown"
        ])
    case .organic:
        Analytics.track("install_organic")
    case .error(let message):
        print("Attribution failed: \(message)")
    }
}

Event tracking

TraceClient.shared.trackEvent(
    name: "purchase_completed",
    properties: [
        "value": "49.99",
        "currency": "USD",
        "product_id": "SKU_123"
    ]
)

See Event Tracking for best practices.

SKAdNetwork

Trace automatically handles SKAdNetwork postbacks on iOS. To update conversion values:

TraceClient.shared.updateConversionValue(42)

Associated Domains

To enable Universal Links, add your Trace domain to your app’s Associated Domains entitlement in Xcode:

applinks:yourapp.traceclick.io

And configure your apple-app-site-association file on your Trace subdomain.