> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dashlink.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Android SDK

> Install the Dashlink Android SDK, receive App Links, and recover the original content after a Play Store install.

Routing (opening an already-installed app from `https://yourbrand.dshl.in/Ab12Cd`) is an OS App Link and does **not** require this SDK. Recovering the original content after a Play Store install, and joining that first open to the store tap, **does**.

```kotlin theme={null}
Dashlink.configure(this, "dlk_sdk_…")
Dashlink.getInstance(this).getDynamicLink(intent)
    .addOnSuccessListener { pending ->
        pending?.appUrl?.let { /* navigate */ }
    }
```

`pending.appUrl`, `pending.utmSource` / `utmMedium` / `utmCampaign`, `pending.isDeferred`, and `pending.clickId` come from the [JSON resolve](https://docs.dashlink.ai/guides/app-dynamic-links/receive.md) body.

The SDK resolves App Links and recovers the original destination on first open after a Play Store install, joining that open to the same `click_id` as the store tap.

## When you need the SDK

| You have | Use |
| - | - |
| App installed, Dynamic Link host declared, OS verified | The OS delivers the short URL. Parse it, or call JSON resolve. The SDK is optional. |
| First open after a Play install from a Dynamic Link | Keep the SDK. It reads Play Install Referrer, navigates to `app_url`, and publishes `deferred_open` with the same `click_id` as the store tap. |
| Later launches | Deferred is not re-run. |

Without the SDK, a fresh install opens on the home screen and the store tap cannot be joined to first open. See [Receive](https://docs.dashlink.ai/guides/app-dynamic-links/receive.md) for the routing vs deferred map.

## Install

Maven coordinates will be published as `ai.dashlink:dashlink-android:1.0.0`. Until then, include the `library` module or build an AAR from the [dashlink-android](https://github.com/Dashlink-ai/dashlink-android) repo.

```kotlin theme={null}
dependencies {
    implementation("ai.dashlink:dashlink-android:1.0.0")
}
```

Min SDK 21. The library depends on [Play Install Referrer](https://developer.android.com/google/play/installreferrer).

## Dynamic Link API key

JSON resolve that writes tracking requires a **Dynamic Link** API key. REST keys (`dlk_live_`) are rejected.

1. In the dashboard, go to **Settings → API Keys → Type Dynamic Link**.
2. Copy the `dlk_sdk_…` key once and call `Dashlink.configure` before `getInstance` / `getDynamicLink`.
3. The SDK sends it as `X-API-Key` (header only). A leaked APK key can hit that org's resolve URL; it cannot call the dashboard REST API.

See [API keys](https://docs.dashlink.ai/guides/api-keys.md).

```kotlin theme={null}
Dashlink.configure(this, "dlk_sdk_…")
```

## Declare the Dynamic Link host

Dashlink already hosts `assetlinks.json` on the Dynamic Link domain. The app must still declare that **host**. App Links are host-wide: put an `autoVerify` intent-filter on `{subdomain}.dshl.in`, not only the marketing site.

```xml theme={null}
<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" android:host="yourbrand.dshl.in" />
</intent-filter>
```

Without this, Chrome never hands the tap to the app — Play opens even if the app is installed. The SDK cannot invent OS intercept. Reinstall after adding the filter so verification runs again.

Fingerprints, Auto vs Manual mode, and Play App Signing live on [App association](https://docs.dashlink.ai/guides/app-dynamic-links/app-association.md).

```bash theme={null}
adb shell pm get-app-links com.example.app
```

Expect the Dynamic Link host listed as verified.

## Receive live taps

Call `getDynamicLink` from the Activity that handles the VIEW intent, and from `onNewIntent` if `launchMode` is `singleTop` / `singleTask`.

```kotlin theme={null}
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        Dashlink.configure(this, "dlk_sdk_…")
        Dashlink.getInstance(this)
            .setDynamicLinkHosts(listOf("yourbrand.dshl.in"))
        handle(intent)
    }

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

    private fun handle(intent: Intent?) {
        Dashlink.getInstance(this).getDynamicLink(intent)
            .addOnSuccessListener { pending ->
                val url = pending?.appUrl ?: return@addOnSuccessListener
                // Route to the screen for url
            }
            .addOnFailureListener { /* retry UX; do not swallow */ }
    }
}
```

`setDynamicLinkHosts` restricts which https URLs the SDK treats as Dashlink short URLs. If you skip it, any https intent with a back-half is resolved.

On an installed tap the SDK JSON-resolves the short URL (`deferred=0`, `match=direct`), returns `app_url`, and analytics records `app_open`. The query parameters the SDK sends are listed on [Receive](https://docs.dashlink.ai/guides/app-dynamic-links/receive.md).

## Deferred first-open

When the app is missing, Dashlink 302s to the Play listing with:

```
referrer=<urlencoded https://{host}/{back_half}?dl_cid={click_id}>
```

On **first open after install** the SDK:

1. Calls Play Install Referrer once.
2. Decodes that URL.
3. JSON-resolves with `deferred=1`, `match=referrer`, and the recovered `click_id`.
4. Returns `PendingDynamicLink` (`appUrl`, UTMs, `isDeferred=true`, `clickId`).
5. Marks deferred **consumed** in SharedPreferences (`ai.dashlink.sdk` / `deferred_consumed`) so a later launch does not re-fire.

If `intent.data` is already a Dashlink URL (installed tap), that wins and referrer is skipped.

A 401 on JSON resolve means the key is missing, not a Dynamic Link key, revoked, or bound to another organization — no `deferred_open` is published.

### Misses

An empty referrer, a foreign URL, or a referrer that is not this app's Dynamic Link host is a **miss**. The SDK still marks deferred consumed. There is no silent home-screen drop that looks like success in analytics: the first-open path either yields `deferred_open` (when a joinable URL was recovered) or nothing to navigate.

A miss is expected when the user installed from Play search rather than the Dynamic Link, or when Play stripped the referrer.

Clearing app data re-runs recovery. Reinstall without data clear may still see Play's cached referrer — Play documents that the referrer API is valid for a limited window after install.

Recovery uses the Play Install Referrer value only. If the user never opened Play through a Dynamic Link that carried `referrer=`, or Play did not return that referrer, there is no destination to recover.

## Tracking

The store 302 is the **click**. SDK JSON resolve is an **outcome on that click** when `click_id` matches, not a second campaign click.

| Event | When | Join |
| - | - | - |
| `store_redirect` | Browser path, app missing | Edge mints `click_id`, puts `dl_cid` on Play `referrer` |
| `deferred_open` | First open, referrer recovered | Same `click_id` |
| `deferred_miss` | First open, nothing recoverable | First-open only; no join if there was no URL |
| `app_open` | Installed tap, JSON resolve | New `click_id` |

Campaign totals should unique-count by `click_id`. Do not add `deferred_open` to click volume. Replay of the same `click_id` still returns `app_url` but does not publish a second `deferred_open`.

## Test on a device

Simulators do not exercise App Link verification the way a real device does.

**1. Uninstall the app**

So the next tap takes the store path.

**2. Tap a staging Dynamic Link**

The device 302s to Play. The referrer carries the short URL and `dl_cid`.

**3. Install the debug APK**

Sideload the build that includes the SDK and the `autoVerify` filter.

**4. Open once**

First open must land on `app_url`. Analytics must show `deferred_open` for the same `click_id` as the store tap.

If an installed tap still opens Chrome, the problem is almost always [app association](https://docs.dashlink.ai/guides/app-dynamic-links/app-association.md), not the SDK.

## Sample and changelog

The [sample app](https://github.com/Dashlink-ai/dashlink-android/tree/main/sample) is a debug receiver for the live-tap and deferred path. Release notes live in the [changelog](https://github.com/Dashlink-ai/dashlink-android/blob/main/CHANGELOG.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.