Testing & Troubleshooting

Testing deferred links on iOS has platform constraints (App Store redirect chain, first-launch-only semantics).

Deferred flow constraints

• Deferred matching is expected on first launch after install.
• SDK stores the first-entrance flag in UserDefaults. Later launches return an empty result for the deferred fallback.
• Session handling is single-pass. Repeated startup resolution in one session is skipped.

Recommended deferred test flow

1. Uninstall the app from the device or simulator.
2. Open a Detour link.
3. Install and launch the app.
4. Verify result.link?.type == .deferred and expected route mapping.
5. Reopen app and confirm deferred link is not consumed again.

For local iteration without reinstall every time:

Detour.shared.resetSession(allowDeferredRetry: true)

Testing runtime links

Simulator custom scheme

xcrun simctl openurl booted "myapp://products/42"

Expected: runtime processLink resolves to .scheme.

Simulator universal link

xcrun simctl openurl booted "https://<your-detour-domain>/products/42"

Expected: runtime processLink resolves to .verified when associated domains are configured.

Common issues

No link handled on cold start

Ensure resolveInitialLink(config:launchOptions:), or the connectionOptions overload, is called once at startup.

Universal links open Safari instead of the app

Verify the associated domains entitlement and the domain configuration in the Dashboard.

Universal link resolves to no route despite a valid click

Your plan’s click limit may be exceeded. Look for [Detour:CLICK_LIMIT_ERROR] in the unified log (subsystem com.swmansion.detour). See Click limits.

Scheme links do nothing

Verify CFBundleURLTypes in Info.plist.

Expected scheme link is ignored

Check linkProcessingMode: .webOnly and .deferredOnly intentionally skip non-web URL-like links.

Analytics events missing in the Dashboard

Ensure analytics is mounted. resolveInitialLink mounts it automatically, and a manual flow can call mountAnalytics.

Debugging

SDK logs through Apple unified logging under subsystem com.swmansion.detour.

On simulator/device:

xcrun simctl spawn booted log stream --predicate 'subsystem == "com.swmansion.detour"'

For end-to-end setup template, use Examples.