# 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:

```swift
Detour.shared.resetSession(allowDeferredRetry: true)
```

## Testing runtime links

### Simulator custom scheme

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

Expected: runtime `processLink` resolves to `.scheme`.

### Simulator universal link

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

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

## Common issues

<details id="no-link-handled-on-cold-start">
<summary>No link handled on cold start</summary>

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

</details>

<details id="universal-links-open-safari">
<summary>Universal links open Safari instead of the app</summary>

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

</details>

<details id="click-limit-error">
<summary>Universal link resolves to no route despite a valid click</summary>

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](https://detour.swmansion.com/docs/sdk/ios/sdk-usage#click-limits).

</details>

<details id="scheme-links-do-nothing">
<summary>Scheme links do nothing</summary>

Verify `CFBundleURLTypes` in `Info.plist`.

</details>

<details id="expected-scheme-link-is-ignored">
<summary>Expected scheme link is ignored</summary>

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

</details>

<details id="analytics-events-missing">
<summary>Analytics events missing in the Dashboard</summary>

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

</details>

## Debugging

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

On simulator/device:

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

For end-to-end setup template, use [Examples](https://detour.swmansion.com/docs/sdk/ios/examples).