iOS Quickstart
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() }
environment: .prodIf you leave out environment, events go to Lucia's staging server and won't appear in
your dashboard.
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
- Want in-app purchases in Lucia? Use the interim conversions request.
- Shipping to the App Store? Read Privacy & App Store.
- Every option and error: iOS Reference.