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.

Troubleshooting checklist

• No link handled on cold start
  • ensure resolveInitialLink(config:launchOptions:) (or connectionOptions overload) is called once at startup.
• Universal links open Safari instead of app
  • verify associated domains entitlement and Dashboard domain configuration.
• 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 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.