# Usage

## Use `DetourDelegate` in Activity lifecycle

`DetourDelegate` is the recommended integration for classic Android apps. It wraps coroutine calls to `Detour.processLink(...)` and returns `LinkResult` in a callback.

```kotlin
import android.content.Intent
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import com.swmansion.detour.Detour
import com.swmansion.detour.DetourConfig
import com.swmansion.detour.DetourDelegate
import com.swmansion.detour.models.LinkProcessingMode
import com.swmansion.detour.models.LinkResult

class MainActivity : AppCompatActivity() {
    private val detourDelegate = DetourDelegate(
        lifecycleOwner = this,
        config = DetourConfig(
            apiKey = BuildConfig.DETOUR_API_KEY,
            appId = BuildConfig.DETOUR_APP_ID,
            linkProcessingMode = LinkProcessingMode.ALL,
        ),
        onLinkResult = { result -> handleLinkResult(result) }
    )

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        Detour.initialize(this, detourDelegate.config)
        detourDelegate.onCreate(intent)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        setIntent(intent)
        detourDelegate.onNewIntent(intent)
    }

    private fun handleLinkResult(result: LinkResult) {
        // handle result and navigate
    }
}
```

If you want complete, runnable integrations for each navigation style, go to [Examples](https://detour.swmansion.com/docs/sdk/android/examples).

## `LinkResult` handling

`processLink()` / `getDeferredLink()` return one of:

- `LinkResult.Success` — contains `url`, `route`, `pathname`, `params`, `type`
- `LinkResult.NotFirstLaunch` — deferred flow already consumed in this install/session
- `LinkResult.NoLink` — no matching link
- `LinkResult.Error` — runtime/integration error

Typical routing pattern:

```kotlin
when (result) {
    is LinkResult.Success -> navigateToRoute(result.route, result.params)
    is LinkResult.NotFirstLaunch -> Unit
    is LinkResult.NoLink -> Unit
    is LinkResult.Error -> Log.e("Detour", "Link error", result.exception)
}
```

## Choose `linkProcessingMode`

`DetourConfig.linkProcessingMode` controls which link sources are handled:

| Value | Deferred | App Links (`http/https`) | Custom scheme |
| --- | --- | --- | --- |
| `ALL` (default) | Yes | Yes | Yes |
| `WEB_ONLY` | Yes | Yes | No |
| `DEFERRED_ONLY` | Yes | No | No |

Use `DEFERRED_ONLY` when your navigation stack already handles app-link/scheme intents and Detour should only resolve first-install deferred links.

## Deferred-only manual flow

In `DEFERRED_ONLY`, you can skip `DetourDelegate` and call `Detour.getDeferredLink()` directly:

```kotlin
Detour.initialize(
    this,
    DetourConfig(
        apiKey = BuildConfig.DETOUR_API_KEY,
        appId = BuildConfig.DETOUR_APP_ID,
        linkProcessingMode = LinkProcessingMode.DEFERRED_ONLY,
    )
)

lifecycleScope.launch {
    when (val result = Detour.getDeferredLink()) {
        is LinkResult.Success -> navigateToRoute(result.route, result.params)
        else -> Unit
    }
}
```

See the `example-deferred-only` app in [Examples](https://detour.swmansion.com/docs/sdk/android/examples).

## Analytics module

`DetourAnalytics` is initialized together with `Detour.initialize(...)`.

```kotlin
import com.swmansion.detour.analytics.DetourAnalytics
import com.swmansion.detour.analytics.DetourEventNames

DetourAnalytics.logEvent(
    DetourEventNames.Purchase,
    mapOf("item" to "subscription_premium", "currency" to "USD"),
)

DetourAnalytics.logRetention("home_screen_opened")
```

## Related pages

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