iOS Deep Links

Supported on: iOS SDK 1.0.61+

The deep links module handles deferred deep links — routing users to the correct screen on first launch after installing from a link. This enables attribution tracking, referral programs, and contextual first-launch experiences.

Deferred Deep Links

A deferred deep link works across the install boundary:

User clicks a link on the web (e.g., https://yourapp.com/workout/123?ref=instagram)
User is redirected to the App Store and installs your app
On first launch, the SDK resolves the original link and returns the destination

AppDNA.checkDeferredDeepLink { deepLink in
    guard let deepLink = deepLink else { return }
    // deepLink.screen = "/workout/123"
    // deepLink.params = ["ref": "instagram"]
    navigate(to: deepLink.screen, params: deepLink.params)
}

checkDeferredDeepLink is a static method on AppDNA. It should be called once on first launch, typically after configure() completes. The SDK returns nil if no deferred link is found or if the app was not installed from a link.

The one-chance rules

Three things about checkDeferredDeepLink that decide whether a link is ever resolved:

Rule	What it means for you
First launch only	The check runs once per install. After it has an answer, every later call returns `nil` without asking the server — so a later screen cannot “check again”. Call it after `configure()` on the first launch and route from the result.
The link expires after 72 hours	A deferred link older than 72 hours is treated as absent and the stored context is deleted when the SDK reads it. A user who installs four days after clicking lands on your default screen.
One-time use	A resolved link is deleted as it is read, so reinstalling does not replay it.

A failed check does not spend the chance. If the first launch cannot reach the server — no network, or Firestore’s first connection has not completed — the SDK keeps the chance and retries on the next launch, up to 4 attempts in all, then gives up and logs giving up after 4 failed attempts. A SUCCESSFUL read is an answer whether or not it found a link, and does spend it. So a user who opens your app on a plane straight after installing still gets their link on their next launch.A transport failure used to spend the chance: the link and its referrer were lost permanently, and your handler received nil, which is indistinguishable from an install that did not come from a link.

Deferred Deep Link Check

checkDeferredDeepLink is a top-level static method, not part of the deep links module:

AppDNA.checkDeferredDeepLink { deepLink in
    guard let deepLink = deepLink else { return }
    navigate(to: deepLink.screen, params: deepLink.params)
}

Module Access

let deepLinks = AppDNA.deepLinks

Module Methods

Method	Signature	Description
`setDelegate`	`setDelegate(_ delegate: AppDNADeepLinkDelegate?)`	Set a delegate for deep link callbacks
`handleURL`	`handleURL(_ url: URL)`	Pass an incoming URL to the SDK for processing

DeferredDeepLink

Property	Type	Description
`screen`	`String`	Target screen path (e.g., `"/workout/123"`)
`params`	`[String: String]`	Additional parameters (e.g., referrer, campaign)
`visitorId`	`String`	The visitor identifier from the originating link

AppDNADeepLinkDelegate

protocol AppDNADeepLinkDelegate: AnyObject {
    func onDeepLinkReceived(url: URL, params: [String: String])
}

Example Implementation

class LinkHandler: AppDNADeepLinkDelegate {
    func onDeepLinkReceived(url: URL, params: [String: String]) {
        // Route based on the incoming URL
        route(to: url.path, params: params)
    }

    private func route(to screen: String, params: [String: String]) {
        switch screen {
        case let s where s.hasPrefix("/workout/"):
            let id = String(s.dropFirst("/workout/".count))
            showWorkout(id: id)
        case "/referral":
            showReferralWelcome(referrer: params["ref"])
        default:
            showHome()
        }
    }
}

AppDNA.deepLinks.setDelegate(LinkHandler())

Platform Setup

Universal Links

To support Universal Links on iOS, configure your app:

Enable Associated Domains in your target’s Signing & Capabilities.
Add your domain: applinks:yourapp.com
Host an apple-app-site-association file on your domain.

Handling in AppDelegate or SceneDelegate

Pass incoming URLs to the SDK:

// SceneDelegate
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    if let url = userActivity.webpageURL {
        AppDNA.deepLinks.handleURL(url)
    }
}

// Or in SceneDelegate for URL schemes
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    if let url = URLContexts.first?.url {
        AppDNA.deepLinks.handleURL(url)
    }
}

Auto-Tracked Events

Event	Trigger
`deferred_deep_link_resolved`	A deferred deep link is resolved on first launch

Full Example

import AppDNASDK

class AppCoordinator: AppDNADeepLinkDelegate {
    init() {
        AppDNA.deepLinks.setDelegate(self)
    }

    func handleFirstLaunch() {
        // Check for deferred deep link on first launch
        AppDNA.checkDeferredDeepLink { [weak self] deepLink in
            if let deepLink = deepLink {
                // User installed from a link -- route to the target screen
                self?.route(to: deepLink.screen, params: deepLink.params)

                // Track the visitor as a user trait
                AppDNA.identify(
                    userId: currentUserId,
                    traits: ["visitor_id": deepLink.visitorId]
                )
            } else {
                // Normal install -- show default onboarding
                self?.showOnboarding()
            }
        }
    }

    // MARK: - AppDNADeepLinkDelegate

    func onDeepLinkReceived(url: URL, params: [String: String]) {
        route(to: url.path, params: params)
    }

    private func route(to screen: String, params: [String: String]) {
        // Route to the correct screen based on the path
    }
}

Deep link routes are configured in the Console under Engagement > Deep Links. The SDK resolves deferred links by checking stored visitor context on first launch.

​Deferred Deep Links

​The one-chance rules

​Deferred Deep Link Check

​Module Access

​Module Methods

​DeferredDeepLink

​AppDNADeepLinkDelegate

​Example Implementation

​Platform Setup

​Universal Links

​Handling in AppDelegate or SceneDelegate

​Auto-Tracked Events

​Full Example

Deferred Deep Links

The one-chance rules

Deferred Deep Link Check

Module Access

Module Methods

DeferredDeepLink

AppDNADeepLinkDelegate

Example Implementation

Platform Setup

Universal Links

Handling in AppDelegate or SceneDelegate

Auto-Tracked Events

Full Example