Deferred Deep Links

Deferred deep links let you route users to specific content even when they don't have your app installed. The user clicks a link, installs from the App Store, and on first launch the SDK matches them back to the original link.

How It Works

1. User taps a WarpLink URL in Safari
2. WarpLink's redirect page collects browser signals (IP, User-Agent, screen size, timezone)
3. User is redirected to the App Store
4. User installs and opens the app
5. SDK detects first launch (tracked via UserDefaults)
6. SDK collects device signals (screen size, timezone, languages, IDFV)
7. SDK sends signals to the attribution API
8. Server matches against stored click data and returns the deep link

Check for Deferred Deep Links

Call checkDeferredDeepLink once, early in your first-launch flow:

WarpLink.checkDeferredDeepLink { result in
    switch result {
    case .success(let deepLink):
        guard let deepLink = deepLink else {
            // No deferred deep link — show default onboarding
            showOnboarding()
            return
        }

        // Route based on confidence
        let confidence = deepLink.matchConfidence ?? 0

        if confidence > 0.5 {
            // High confidence — route to specific content
            if let deepLinkUrl = deepLink.deepLinkUrl {
                navigateTo(deepLinkUrl)
            } else {
                navigateTo(deepLink.destination)
            }
        } else {
            // Low confidence — show generic welcome with a hint
            showWelcome(suggestedContent: deepLink.destination)
        }

    case .failure(let error):
        // Network error on first launch — show default experience
        print("Deferred deep link error: \(error.localizedDescription)")
        showOnboarding()
    }
}

Confidence Scores

Recommendation: Route to specific content when matchConfidence > 0.5. Show generic onboarding below 0.5.

Match Window

The match window controls how far back the server looks for matching clicks. Default is 72 hours.

WarpLink.configure(
    apiKey: "wl_live_your_api_key_here_abcdefgh",
    options: WarpLinkOptions(matchWindowHours: 48)
)

A shorter window reduces false positives but may miss users who take longer to install.

Caching Behavior

• The SDK checks for a deferred deep link only on first launch
• The result (match or no match) is cached in UserDefaults
• Subsequent calls return the cached result without a network request
• Attribution happens exactly once per app install

Edge Cases

Offline First Launch

If the device has no connectivity on first launch, checkDeferredDeepLink fails with .networkError. The first-launch flag is consumed, so retrying later returns the cached nil result.

App Reinstall

UserDefaults may persist across app delete/reinstall depending on iOS version and iCloud backup. If it persists, the SDK treats it as a subsequent launch and returns the cached result.

Multiple Links Before Install

If a user clicks multiple WarpLink URLs before installing, only the most recent click is matched.

Testing Deferred Deep Links

1. Delete the app from your test device
2. Open the test link in Safari — you'll be redirected to the App Store (or fallback URL)
3. Install the app via Xcode or TestFlight
4. Launch the app — checkDeferredDeepLink should return the matched deep link