# Installation

Detour provides an Android SDK (`com.swmansion.detour:detour-sdk`) for deferred deep links, App Links, and custom scheme links.

:::tip[AI agent skills]
Detour ships two AI coding-agent skills: `detour-onboarding` for a setup from scratch, and `migrate-to-detour` for moving off Branch or AppsFlyer. Both cover this page. See [Detour Skills](https://detour.swmansion.com/docs/platform/fundamentals/skills).
:::

A Detour app in the Dashboard is required before the SDK can resolve links. See [Getting Started](https://detour.swmansion.com/docs/platform/fundamentals/getting-started).

## Requirements

- Android min SDK: `21` (Android 5.0+)
- Kotlin: `2.0+`
- JVM target: `11`

The SDK calls the Detour API over the network, so it needs the two standard
Android network permissions, `INTERNET` and `ACCESS_NETWORK_STATE`. It declares
both in its own manifest and manifest merging adds them to your app, so there is
nothing to add to your `AndroidManifest.xml`.

## Add dependency

```kotlin
    dependencies {
      implementation("com.swmansion.detour:detour-sdk:1.1.0")
    }
    ```
  ```groovy
    dependencies {
      implementation "com.swmansion.detour:detour-sdk:1.1.0"
    }
    ```
  ## Credentials

Both values come from **API configuration** in the Dashboard: the `appId` and the publishable `apiKey`. See [Getting Started](https://detour.swmansion.com/docs/platform/fundamentals/getting-started#api-configuration).

Store credentials outside source control and pass them through `BuildConfig`, the way the SDK examples do:

```kotlin title="app/build.gradle.kts"
buildConfigField("String", "DETOUR_API_KEY", "\"${secrets["DETOUR_API_KEY"] ?: ""}\"")
buildConfigField("String", "DETOUR_APP_ID", "\"${secrets["DETOUR_APP_ID"] ?: ""}\"")
```

```kotlin
// Activity/Application code
val config = DetourConfig(
    apiKey = BuildConfig.DETOUR_API_KEY,
    appId = BuildConfig.DETOUR_APP_ID
)
```

## Initialization

Call `Detour.initialize(...)` once, before any link is processed.

```kotlin
Detour.initialize(applicationContext, config)
```

`Application.onCreate()` is the usual place. The first activity works too, as long as it runs before `processLink()` or `getDeferredLink()`.

## Manifest integration

Android only dispatches a link to your app if a `VIEW` intent filter claims it.
Add the filters to the activity that passes incoming intents to Detour.

### Verified App Links

Copy the generated filter from
[**App configuration**](https://detour.swmansion.com/docs/platform/fundamentals/getting-started#app-configuration)
in the Dashboard. It has this structure:

```xml title="AndroidManifest.xml"
<activity
    android:name=".MainActivity"
    android:exported="true">
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="https" />
        <data android:host="<your-host>" />
        <data android:pathPrefix="/<app-hash>" />
        <!-- The Dashboard adds any required legacy short-link prefixes. -->
    </intent-filter>
</activity>
```

Keep the generated values rather than copying the placeholders above. New short
links reuse `/<app-hash>` and do not require another manifest entry or native
build.

If your app is served from a [custom domain](https://detour.swmansion.com/docs/platform/advanced/custom-domain),
the Dashboard generates the filter for that domain. Assign the domain before
you copy the values. Changing the host an app is assigned to later needs a new
build. Do not add hosts it did not generate: on
Android 11 and lower that breaks App Link verification for every host at once,
see [Verification](https://detour.swmansion.com/docs/platform/fundamentals/universal-app-links#verification).

### Custom-scheme links (optional)

The Dashboard does not generate custom-scheme registration. If your app uses
links such as `myapp://product/42`, add a separate filter to the same activity:

```xml title="AndroidManifest.xml"
<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="myapp" />
</intent-filter>
```

The [`example`](https://github.com/software-mansion-labs/android-detour/blob/main/examples/example/README.md)
app shows the completed manifest and activity integration.

## Next steps

1. Wire `DetourDelegate` or manual processing in [Usage](https://detour.swmansion.com/docs/sdk/android/sdk-usage).
2. Pick the closest runnable pattern in [Examples](https://detour.swmansion.com/docs/sdk/android/examples).