iOS SDK - Datalyr Docs

Complete reference for DatalyrSDK 2.1.10, which posts events to https://ingest.datalyr.com/track. For a first install, start with Install in a mobile app.

Requirements

Item	Value
Minimum iOS	13.0
Swift tools version	5.7
Current release	2.1.10
Frameworks linked	`Foundation`, `UIKit`, `StoreKit`, `AdServices` (weak)

Install

Swift Package Manager
CocoaPods

In Xcode, open File → Add Package Dependencies. Add this URL.

https://github.com/datalyr/swift

Add the DatalyrSDK product to your app target.

.package(url: "https://github.com/datalyr/swift", from: "2.1.12")

pod 'DatalyrSDK', '~> 2.1.10'

Run pod install. Open the generated .xcworkspace.

App Store review requires a privacy manifest. Add your own PrivacyInfo.xcprivacy, or install with Swift Package Manager, which ships one.

Initialize

Call configure once, at app launch. Generate a write key under Settings → API.

import DatalyrSDK

@main
struct MyApp: App {
    init() {
        Task {
            try await DatalyrSDK.configure(apiKey: "dk_your_api_key")
        }
    }
    var body: some Scene { WindowGroup { ContentView() } }
}

initialize(config:) throws DatalyrError.invalidApiKey on an empty key. The SDK buffers up to 50 events, 50 identity calls, and 50 deep links sent before initialization.

What the SDK tracks without your code

Wire event name	Trigger
`app_install`	First `initialize()` on a device
`session_start`	`initialize()`, and foreground after the session ended
`session_end`	Inactivity timer, `willTerminateNotification`, or SDK teardown
`$att_status`	Every `updateTrackingAuthorization()` call
`$web_attribution_matched`	An email or IP lookup matched an earlier web visit

The SDK never prompts for App Tracking Transparency on its own, and it never captures the launch URL. Call handleDeepLink(_:) yourself.

Events the SDK sends for you

These names are reserved. Never send one through track().

Method you call	Wire event name
`screen()`, `.datalyrScreen()`	`pageview`
`identify()`	`$identify`
`alias()`	`$alias`
`handleDeepLink()`	`$deep_link`
`trackAppUpdate()`	`app_update`
`trackPurchase()`	`purchase`
`trackSubscription()`	`subscribe`
`trackAddToCart()`	`add_to_cart`
`trackViewContent()`	`view_content`
`trackInitiateCheckout()`	`initiate_checkout`
`trackCompleteRegistration()`	`complete_registration`
`trackSearch()`	`search`
`trackLead()`	`lead`
`trackAddPaymentInfo()`	`add_payment_info`

screen() sends an event named pageview, not screen. Filter on pageview in Events.

Event names accept [A-Za-z0-9_-.$] up to 100 characters. Whitespace runs collapse to _, so track("Order Completed") arrives as Order_Completed.

Track an event

await datalyrTrack("signup_completed", eventData: [
    "plan": "pro",
    "seats": 5
])

Track a screen

SwiftUI
UIKit

PricingView()
    .datalyrScreen("Pricing", properties: ["variant": "A"])

DatalyrSDK.enableAutomaticScreenTracking()
DatalyrSDK.excludedScreenClasses = ["UINavigationController"]

Identity

Call identify() once per signed-in person, not on every screen. A call with a different userId runs reset() first, which rotates the anonymous ID and erases attribution, the journey, and the SKAdNetwork high-water value.

// Pass your database user ID, not an email. Emails change, and a changed
// email creates a second user with a split journey.
await datalyrIdentify("user_123", properties: [
    "email": "[email protected]",
    "plan": "pro"
])

A repeat call with unchanged ID and traits sends no $identify event.

Identity on the wire

Wire field	Value
`anonymousId`	Top-level. Format `anon_<UUID>`.
`properties.anonymous_id`	The same value, repeated.
`userId`	Your ID from `identify()`. The key is absent until then.
`properties.sessionId`	A bare UUID. No prefix.
`context.session_id`	The same session UUID. This is the field Datalyr reads.
`properties.fingerprint.deviceId`	A bare UUID for the install.

This SDK sends no distinct_id and no top-level visitor_id. To pass identity to RevenueCat or Superwall, use getRevenueCatAttributes() or getSuperwallAttributes().

await datalyrReset()
let anonymousId = datalyrGetAnonymousId()

reset() rotates the anonymous ID and session, and clears attribution, journey, and SKAdNetwork state.

Revenue

await datalyrTrackPurchase(value: 99.99, currency: "USD", productId: "pro_yearly")
await datalyrTrackSubscription(value: 19.99, currency: "USD", plan: "pro_monthly")

trackPurchase, trackSubscription, trackAddToCart, trackInitiateCheckout, trackCompleteRegistration, and trackLead update the SKAdNetwork conversion value. trackViewContent, trackSearch, and trackAddPaymentInfo do not.

Attribution

Pass every incoming link to the SDK.

// Every link, every time. A link you skip is a campaign you can't credit.
.onOpenURL { url in
    Task { await DatalyrSDK.shared.handleDeepLink(url) }
}

The SDK reads these 38 parameters from the query string and the URL fragment. Key matching is case-insensitive.

Group	Parameters
Datalyr	`lyr`, `datalyr`, `dl_tag`, `dl_campaign`
Click IDs	`fbclid`, `ttclid`, `gclid`, `wbraid`, `gbraid`, `dclid`, `twclid`, `li_click_id`, `msclkid`, `oppref`
Click ID aliases	`tt_click_id` and `tiktok_click_id` both store as `ttclid`
UTM	`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `utm_id`, `utm_source_platform`, `utm_creative_format`, `utm_marketing_tactic`
Partner	`partner_id`, `affiliate_id`, `referrer_id`, `source_id`
Ad structure	`campaign_id`, `ad_id`, `adset_id`, `creative_id`, `placement_id`, `keyword`, `matchtype`, `network`, `device`

Each utm_* value is mirrored to campaign_source, campaign_medium, campaign_name, campaign_term, and campaign_content. Since 2.1.9 the whole attribution record rides on every event. Properties you pass to track() win on a name collision.

Apple Search Ads

The SDK reads AdServices on iOS 14.3 and later, and adds these 12 properties to every event: asa_attribution, asa_org_id, asa_org_name, asa_campaign_id, asa_campaign_name, asa_adgroup_id, asa_adgroup_name, asa_conversion_type, asa_click_date, asa_keyword, asa_keyword_id, asa_region. The fetch does not block initialize(), so the first events after install carry no asa_* values.

SKAdNetwork

initialize() registers for attribution. The framework depends on the OS version.

iOS version	Framework used
17.4 and later	AdAttributionKit
16.1 to 17.3	SKAdNetwork 4.0
14.0 to 16.0	SKAdNetwork 3.0

Conversion values only ever increase. The SDK stores a high-water fine value and sends an update only for a strictly higher fine value, or an equal fine value with a higher coarse value.

Set skadTemplate at initialization to use conversion values. Without it, getConversionValue(for:) returns nil and trackWithSKAdNetwork() sends no postback update. Pass gaming or subscription for those templates. Any other string selects the ecommerce template.

Journey

let journey = DatalyrSDK.shared.getJourney()
let summary = DatalyrSDK.shared.getJourneySummary()

The journey holds up to 30 touchpoints over a 90-day window. It is readable in the app only. The SDK attaches no journey field to any event.

App Tracking Transparency

let status = await DatalyrSDK.shared.requestTrackingAuthorization()

Value	Meaning
`0`	notDetermined
`1`	restricted
`2`	denied
`3`	authorized

Each call sends $att_status and refreshes idfa, att_status, and advertiser_tracking_enabled on later events. The SDK caches advertiser data once at initialization, so call this after the prompt resolves. ATT governs the advertising identifier. It is not an analytics consent system. Your app owns consent and the App Store privacy disclosure.

RevenueCat and Superwall

Purchases.shared.setAttributes(DatalyrSDK.shared.getRevenueCatAttributes())
Superwall.shared.setUserAttributes(DatalyrSDK.shared.getSuperwallAttributes())

Call both after the two SDKs initialize, and again after the ATT prompt. See RevenueCat and Superwall.

Complete method list

Every method below is on DatalyrSDK.shared unless marked static. Each datalyr* free function mirrors its instance method.

Method	Signature
`configure` (static)	`(apiKey: String, workspaceId: String = "", debug: Bool = false) async throws`
`configure` (static)	`(apiKey: String, workspaceId: String = "", debug: Bool = false, enableAutoEvents: Bool = true, enableAttribution: Bool = true) async throws`
`configureWithSKAdNetwork` (static)	`(apiKey: String, workspaceId: String = "", template: String = "ecommerce", debug: Bool = false, enableAutoEvents: Bool = true, enableAttribution: Bool = true) async throws`
`initialize`	`(config: DatalyrConfig) async throws`
`track`	`(_ eventName: String, eventData: EventData? = nil) async`
`screen`	`(_ screenName: String, properties: EventData? = nil) async`
`identify`	`(_ userId: String, properties: UserProperties? = nil) async`
`alias`	`(_ newUserId: String, previousId: String? = nil) async`
`reset`	`() async`
`flush`	`() async`
`handleDeepLink`	`(_ url: URL) async`
`getStatus`	`() -> SDKStatus`
`getAnonymousId`	`() -> String`
`getAttributionData`	`() -> AttributionData`
`setAttributionData`	`(_ data: AttributionData) async`
`getJourney`	`() -> [TouchPoint]`
`getJourneyData`	`() -> [String: Any]`
`getJourneySummary`	`() -> JourneySummary`
`getAppleSearchAdsAttribution`	`() -> AppleSearchAdsAttribution?`
`getPlatformIntegrationStatus`	`() -> [String: Bool]`
`requestTrackingAuthorization`	`() async -> UInt` (iOS 14.5 and later)
`updateTrackingAuthorization`	`(status: UInt? = nil) async`
`isTrackingAuthorized`	`() -> Bool`
`getTrackingAuthorizationStatus`	`() -> UInt`
`getIDFA`	`() -> String?`
`getAdvertiserData`	`() -> [String: Any]`
`getSuperwallAttributes`	`() -> [String: String]`
`getRevenueCatAttributes`	`() -> [String: String]`
`trackAppUpdate`	`(previousVersion: String, currentVersion: String) async`
`trackRevenue`	`(_ eventName: String, properties: EventData? = nil) async`
`trackWithSKAdNetwork`	`(_ event: String, eventData: EventData? = nil) async`
`trackPurchase`	`(value: Double, currency: String = "USD", productId: String? = nil) async`
`trackSubscription`	`(value: Double, currency: String = "USD", plan: String? = nil) async`
`trackAddToCart`	`(value: Double, currency: String = "USD", productId: String? = nil, productName: String? = nil) async`
`trackViewContent`	`(contentId: String? = nil, contentName: String? = nil, contentType: String = "product", value: Double? = nil, currency: String? = nil) async`
`trackInitiateCheckout`	`(value: Double, currency: String = "USD", numItems: Int? = nil, productIds: [String]? = nil) async`
`trackCompleteRegistration`	`(method: String? = nil) async`
`trackSearch`	`(query: String, resultIds: [String]? = nil) async`
`trackLead`	`(value: Double? = nil, currency: String? = nil) async`
`trackAddPaymentInfo`	`(success: Bool = true) async`
`getConversionValue`	`(for event: String, properties: EventData? = nil) -> Int?`
`isInitialized`	`Bool`
`enableAutomaticScreenTracking` (static)	`()` (UIKit only)
`excludedScreenClasses` (static)	`[String]` (UIKit only)

View.datalyrScreen(_:properties:), View.datalyrTrack(_:properties:), and UIViewController.datalyrTrackScreenView() wrap the same calls.

Configuration

let config = DatalyrConfig(
    apiKey: "dk_your_api_key",
    debug: false,
    timeout: 15,       // seconds on iOS, not milliseconds
    batchSize: 10,
    flushInterval: 10, // seconds
    maxQueueSize: 1000
)
try await DatalyrSDK.shared.initialize(config: config)

timeout, retryDelay, and flushInterval are seconds on iOS. The React Native SDK uses milliseconds for the same three names. Copying timeout: 15000 from a React Native configuration produces a 15,000-second timeout.

Option	Type	Default	Unit
`apiKey`	`String`	Required. Throws when empty.	None
`workspaceId`	`String`	`""`	None
`endpoint`	`String`	`"https://ingest.datalyr.com/track"`	URL
`useServerTracking`	`Bool`	`true`	None
`debug`	`Bool`	`false`	None
`maxRetries`	`Int`	`3`	attempts
`retryDelay`	`TimeInterval`	`1.0`	seconds
`timeout`	`TimeInterval`	`15.0`	seconds
`batchSize`	`Int`	`10`	events per drain
`flushInterval`	`TimeInterval`	`10.0`	seconds
`maxQueueSize`	`Int`	`1000`	events
`enableAutoEvents`	`Bool`	`true`	None
`enableAttribution`	`Bool`	`true`	None
`autoEventConfig`	`AutoEventConfig?`	`nil`	None
`skadTemplate`	`String?`	`nil`	`gaming`, `subscription`, or ecommerce

AutoEventConfig

Option	Type	Default	Unit
`trackSessions`	`Bool`	`true`	None
`trackScreenViews`	`Bool`	`true`	None
`autoTrackScreenViews`	`Bool`	`false`	None
`sessionTimeoutMs`	`TimeInterval`	`1800000`	milliseconds (30 minutes)

Note the unit split here: sessionTimeoutMs is milliseconds, and the other three interval options are seconds. sessionTimeoutMs sets when session_end fires. Session ID rotation is fixed at 30 minutes. trackScreenViews: false stops the internal screen counters. It does not stop the pageview event. screen() always sends one.

Options with no effect

Remove these three from your configuration.

DatalyrConfig.respectDoNotTrack
AutoEventConfig.trackAppUpdates. Call trackAppUpdate() yourself.
AutoEventConfig.trackPerformance

Call these instead

Instead of	Call
`getDeferredAttributionData()`	`getAppleSearchAdsAttribution()`
`getLastError()`	`getStatus()`

Limits

Limit	Value
Events drained per pass	10, from `batchSize`
HTTP requests per drain	One per event. There is no batch endpoint.
Flush interval	10 seconds
Retries per event	3
Retry backoff	`min(2^n × retryDelay + random(0…1), 30)` seconds
`Retry-After` honored	Clamped to 0–30 seconds
Extra waits on 429 and 408	5, outside the retry budget
Request timeout	15 seconds. Resource timeout 30 seconds.
Client rate limit	100 requests per 60 seconds. The SDK waits, up to 120 seconds.
Queue	1000 events
Dead-letter queue	100 events
Pre-init buffers	50 events, 50 identity calls, 50 deep links
Event data payload	32,768 bytes of serialized JSON
Event name	100 characters
Journey	30 touchpoints over 90 days
Attribution lookup timeout	10 seconds

How failed requests behave

Response	Behavior
`429`, `408`	Waits for `Retry-After`, then retries. Uses a separate budget of 5 waits.
Other `4xx`	Dropped. A wrong API key produces this.
`5xx`, network failure	Retried with exponential backoff, up to `maxRetries`, then moved to the dead-letter queue.

Storage

The SDK keeps its state in UserDefaults under these keys.

UserDefaults key	Holds
`datalyr_datalyr_anonymous_id`	The anonymous ID
`datalyr_datalyr_visitor_id`	The visitor ID
`datalyr_datalyr_session_id`	The session ID
`datalyr_datalyr_user_id`	The identified user ID
`datalyr_datalyr_event_queue`	The pending queue
`datalyr_datalyr_dead_letter_queue`	Permanently failed events
`datalyr_datalyr_attribution_data`	The attribution record
`datalyr_datalyr_app_install_tracked`	The `app_install` guard
`datalyr_first_touch`, `datalyr_last_touch`, `datalyr_journey`	Journey state
`datalyr_skan_registered`, `datalyr_skan_high_fine`, `datalyr_skan_high_coarse`, `datalyr_skan_window_locked`	SKAdNetwork state

The SDK writes nothing to the Keychain.

Verify the install

Run the app on a clean simulator or a fresh install.
Open Events in Datalyr.
Confirm app_install and session_start arrive within 30 seconds.

If nothing arrives, call getStatus() and read initialized and queueStats. A queue that grows without draining means the API key is wrong. See No events.

​Requirements

​Install

​Initialize

​What the SDK tracks without your code

​Events the SDK sends for you

​Track an event

​Track a screen

​Identity

​Identity on the wire

​Revenue

​Attribution

​Apple Search Ads

​SKAdNetwork

​Journey

​App Tracking Transparency

​RevenueCat and Superwall

​Complete method list

​Configuration

​AutoEventConfig

​Options with no effect

​Call these instead

​Limits

​How failed requests behave

​Storage

​Verify the install

Requirements

Install

Initialize

What the SDK tracks without your code

Events the SDK sends for you

Track an event

Track a screen

Identity

Identity on the wire

Revenue

Attribution

Apple Search Ads

SKAdNetwork

Journey

App Tracking Transparency

RevenueCat and Superwall

Complete method list

Configuration

AutoEventConfig

Options with no effect

Call these instead

Limits

How failed requests behave

Storage

Verify the install