iOS Reference
Reference for LuciaMetricsSDK 2.1.x (beta). The API may change before the SDK leaves beta.
captureDeviceFingerprint
Starts the SDK: asks for tracking permission, registers the device, and returns its Lucia ID. Call it on the main actor once the app is active.
@MainActor
func captureDeviceFingerprint(
versionNumber: String,
buildNumber: String,
appName: String,
userName: String,
environment: MetricsEnvironment = .staging,
tier: DataCollectionTier = .tier1Metrics,
regionPolicy: RegionPolicy = .disableInRestrictedRegions,
retentionPolicy: RetentionPolicy = .default,
overrides: DataMinimizationOverrides = .none,
rateLimitPolicy: RateLimitPolicy = .default,
completion: @escaping @Sendable (Result<String, MetricsError>) -> Void
) async
| Parameter | What to pass |
|---|---|
versionNumber, buildNumber | Your app's version and build, e.g. from CFBundleShortVersionString / CFBundleVersion |
appName | Your app's name |
userName | Your user's ID or email if you know it, otherwise "". Only sent the first time a device registers |
environment | Where to send data. Use .prod for live apps, since the default is .staging |
tier | How much to collect. See tiers. Use .tier2MetricsAndTouch for touch tracking |
regionPolicy | What to do in the EU, UK, and California. See regions |
retentionPolicy | How long data stays on the device |
overrides | Fields to leave out even when the tier allows them |
rateLimitPolicy | Event caps per session and per day |
completion | Called with the Lucia ID, or an error |
After the first success, the Lucia ID is saved on the device. Later calls return it straight away without registering again.
Environments
| Value | Sends to |
|---|---|
.prod | https://api.luciaprotocol.com |
.staging (default) | Lucia's staging server, for testing only |
.develop(url:) | A URL you provide |
Errors
MetricsError | Meaning | What to do |
|---|---|---|
.permissionDenied | The user declined tracking, or the advertising identifier isn't available | Nothing is collected. Don't retry on every launch |
.regionRestricted | The device is in a restricted region and regionPolicy is .disableInRestrictedRegions | Expected. Change regionPolicy if you have consent in place |
.syncFailed(error:) | Registering with Lucia failed (network, wrong API key, server error) | Check LuciaSDKKey and connectivity, then try again later |
.unknown | Anything else | Try again; contact support if it persists |
Touch tracking (iOS 17+)
UIApplication.shared.recordTouches()
Records taps and swipes/drags anywhere in the app's key window, without interfering with your own gestures. Call it on the main actor after the SDK has started and your window is on screen.
- Requires tier
.tier2MetricsAndTouchor higher. On Tier 1, touches are dropped. - Events are sent in batches of 10, or every 10 seconds, whichever comes first.
- Pending events are also sent when the app goes to the background or closes, and when the network comes back.
- If the device is offline, events are stored encrypted on the device and sent later (up to 7 days by default).
Info.plist keys
| Key | Required | Purpose |
|---|---|---|
LuciaSDKKey | Yes | Your Lucia API key |
NSUserTrackingUsageDescription | Yes | The message shown in Apple's tracking prompt |
LuciaSDKPinnedCertHashes | No | Certificate pinning. See Privacy & App Store |
Troubleshooting
The completion handler never reports success
Check that LuciaSDKKey is in Info.plist, that environment is .prod, and that the
tracking prompt was allowed. On the Simulator, reset tracking under Settings → Privacy &
Security → Tracking.
The completion handler is never called (Tier 3)
Known beta issue: on .tier3Full, if the SDK can't read the device's network address (for
example, while offline), it stops without calling completion. Use .tier2MetricsAndTouch
unless you need IP data, or start the SDK again later.
The tracking prompt never appears
iOS only shows it while the app is active, and only once per install. Make sure
NSUserTrackingUsageDescription is set and start the SDK from a view (e.g. SwiftUI .task),
not from didFinishLaunching.
No touch events arrive
Touch tracking needs iOS 17+, tier .tier2MetricsAndTouch or higher, and a key window on screen
when you call recordTouches(). Also check you haven't hit the per-session or per-day cap.
Nothing happens for testers in Europe
That's the default regionPolicy. Switch to .clampToTier1InRestrictedRegions or .allowAll
if you have the right consent in place.