SDK Usage

Define shared config

import Detour

let detourConfig = DetourConfig(
    apiKey: "<YOUR_DETOUR_API_KEY>",
    appID: "<YOUR_DETOUR_APP_ID>",
    shouldUseClipboard: true,
    linkProcessingMode: .all
)

Resolve initial link at startup

Use resolveInitialLink once during cold start (UIApplicationDelegate flow):

func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
    Detour.shared.resolveInitialLink(config: detourConfig, launchOptions: launchOptions) { result in
        if let link = result.link {
            // Navigate using link.route / link.pathname / link.params
        }
    }

    return true
}

If you use scene lifecycle, call the overload with connectionOptions in scene(_:willConnectTo:options:).

If you want complete, runnable integration with AppDelegate + SwiftUI UI state, go to Examples.

Handle runtime links

Custom scheme links (myapp://...)

func application(
    _ app: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
    Task { @MainActor in
        let result = await Detour.shared.processLink(url, config: detourConfig)
        // handle result.link
    }
    return true
}

Universal links (https://...)

func application(
    _ application: UIApplication,
    continue userActivity: NSUserActivity,
    restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL else {
        return false
    }

    Task { @MainActor in
        let result = await Detour.shared.processLink(url, config: detourConfig)
        // handle result.link
    }
    return true
}

DetourResult shape

processLink and resolveInitialLink return:

• processed: link processing finished
• link: DetourLink?

Helpers exposed on DetourResult:

• route
• pathname
• params
• linkType
• linkURL

Choose linkProcessingMode

DetourConfig.linkProcessingMode controls which link sources are handled:

Value	Universal links	Deferred links	Custom scheme links
.all (default)	Yes	Yes	Yes
.webOnly	Yes	Yes	No
.deferredOnly	No	Yes	No

Use .deferredOnly when runtime links are handled by your own routing layer and Detour should resolve only deferred links.

Click limits

When a Universal Link is processed with a non-nil config, the SDK verifies the click against your plan's click limit before delivering the resolved link. While your app is within the limit, links resolve normally. When the limit is exceeded, the link is not delivered — result.link is nil and no navigation happens.

In that case the SDK logs a [Detour:CLICK_LIMIT_ERROR] message (subsystem com.swmansion.detour) with the limit details (clicksInPeriod, effectiveLimit).

This dedicated [Detour:CLICK_LIMIT_ERROR] flow applies only to Universal Links. Deferred-link matching and short-link resolution are subject to the same plan limits on the backend, but the SDK does not surface a dedicated limit error for them — when the limit is exceeded the affected link simply fails to resolve (result.link is nil) instead of logging a click-limit error. Custom scheme links are handled locally and are not limit-checked.

For the actual per-plan click limits, pay-as-you-go overage, and how to raise them, see Billing & Payments.

Fail-open by design

If the limit check cannot complete because of a network or backend error, the SDK lets the link through so a temporary outage never breaks navigation. Limits are enforced only on an explicit "denied" response from the backend.

Analytics

resolveInitialLink(...) mounts analytics automatically.

You can also mount explicitly:

Detour.shared.mountAnalytics(config: detourConfig)

Emit events from app code:

DetourAnalytics.logEvent(.addToCart, data: ["sku": "abc"])
DetourAnalytics.logEvent("promo_banner_tap", data: ["placement": "home_top"])
DetourAnalytics.logRetention("day_7_return")

resolveInitialLink(...) also logs an app_open retention event once per session on cold start — you don't need to call it yourself.

Every request the SDK sends to the Detour backend carries an X-SDK: ios/<version> header. It is used for diagnostics and SDK-usage analysis and requires no configuration.

Related pages

• Examples
• API Reference
• Custom Storage
• Testing & Troubleshooting