Skip to main content
Version: current (0.13)

iOS Quickstart

Beta

The iOS SDK is in beta. It identifies devices and records engagement, but doesn't track in-app conversions yet. See what's included before you start.

You'll need: Xcode with Swift 6.1 or later, an app targeting iOS 14+ (touch tracking needs iOS 17+), and a Lucia API key from app.luciaprotocol.com.

1. Install the package​

In Xcode, choose File → Add Package Dependencies… and enter:

https://github.com/ondecentral/Lucia-iOS-SDK

Pick version 2.1.2 or later and add the LuciaMetricsSDK library to your app target.

Or, in a Package.swift:

.package(url: "https://github.com/ondecentral/Lucia-iOS-SDK", from: "2.1.2")

2. Add your keys to Info.plist​

The SDK reads your API key from Info.plist. Apple also requires a short message explaining why you ask to track. iOS shows it in the permission prompt.

<key>LuciaSDKKey</key>
<string>YOUR_API_KEY</string>

<key>NSUserTrackingUsageDescription</key>
<string>This lets us measure which of our ads brought you here.</string>

3. Start the SDK​

Call captureDeviceFingerprint once the app is active. It shows Apple's tracking prompt, registers the device, and returns its Lucia ID.

import LuciaMetricsSDK

@MainActor
func startLucia() async {
let info = Bundle.main.infoDictionary
await MetricsCollector.shared.captureDeviceFingerprint(
versionNumber: info?["CFBundleShortVersionString"] as? String ?? "",
buildNumber: info?["CFBundleVersion"] as? String ?? "",
appName: "MyApp",
userName: "", // your user's ID or email, if you know it
environment: .prod, // the default is .staging — always set .prod for live apps
tier: .tier2MetricsAndTouch // needed for touch tracking (step 4)
) { result in
switch result {
case .success(let luciaID):
print("Lucia ready:", luciaID)
case .failure(let error):
print("Lucia not started:", error)
}
}
}

In SwiftUI, call it from your root view:

.task { await startLucia() }
Set environment: .prod

If you leave out environment, events go to Lucia's staging server and won't appear in your dashboard.

Show the prompt while the app is on screen

iOS only shows the tracking prompt to an app that's active. Calling startLucia() from a view (as above) rather than from didFinishLaunching makes sure people actually see it.

4. Turn on touch tracking (iOS 17+)​

Once the SDK has started, start recording taps and swipes:

case .success(let luciaID):
if #available(iOS 17, *) {
Task { @MainActor in UIApplication.shared.recordTouches() }
}

Touches are only recorded on tier .tier2MetricsAndTouch or higher, so keep the tier argument from step 3.

5. Check it worked​

  • In Xcode: the console prints Lucia ready: followed by the device's Lucia ID.
  • If you see permissionDenied: the tracking prompt was declined. On the Simulator, reset it under Settings → Privacy & Security → Tracking.
  • If you see regionRestricted: the device's region is the EU, UK, or (approximately) California, where the SDK is off by default. See Privacy & App Store.

What's next​