Skip to main content
Version: current (0.13)

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
ParameterWhat to pass
versionNumber, buildNumberYour app's version and build, e.g. from CFBundleShortVersionString / CFBundleVersion
appNameYour app's name
userNameYour user's ID or email if you know it, otherwise "". Only sent the first time a device registers
environmentWhere to send data. Use .prod for live apps, since the default is .staging
tierHow much to collect. See tiers. Use .tier2MetricsAndTouch for touch tracking
regionPolicyWhat to do in the EU, UK, and California. See regions
retentionPolicyHow long data stays on the device
overridesFields to leave out even when the tier allows them
rateLimitPolicyEvent caps per session and per day
completionCalled 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​

ValueSends to
.prodhttps://api.luciaprotocol.com
.staging (default)Lucia's staging server, for testing only
.develop(url:)A URL you provide

Errors​

MetricsErrorMeaningWhat to do
.permissionDeniedThe user declined tracking, or the advertising identifier isn't availableNothing is collected. Don't retry on every launch
.regionRestrictedThe device is in a restricted region and regionPolicy is .disableInRestrictedRegionsExpected. 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
.unknownAnything elseTry 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 .tier2MetricsAndTouch or 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​

KeyRequiredPurpose
LuciaSDKKeyYesYour Lucia API key
NSUserTrackingUsageDescriptionYesThe message shown in Apple's tracking prompt
LuciaSDKPinnedCertHashesNoCertificate 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.