# Usage

## Define shared config

```swift
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):

```swift
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](https://detour.swmansion.com/docs/sdk/ios/examples).

## Handle runtime links

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

```swift
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://...`)

```swift
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:

<PropertyList>
  <Property name="processed">
    Link processing finished.
  </Property>
  <Property name="link" type={"DetourLink?"} />
</PropertyList>

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.

## Analytics

`resolveInitialLink(...)` mounts analytics automatically.

You can also mount explicitly:

```swift
Detour.shared.mountAnalytics(config: detourConfig)
```

Emit events from app code:

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

## Related pages

- [Examples](https://detour.swmansion.com/docs/sdk/ios/examples)
- [API Reference](https://detour.swmansion.com/docs/sdk/ios/api-reference)
- [Custom Storage](https://detour.swmansion.com/docs/sdk/ios/custom-storage)
- [Testing & Troubleshooting](https://detour.swmansion.com/docs/sdk/ios/testing)