Deep links in a Jetpack Compose app

A Compose app usually has one activity and a NavHost. Links have to get from that activity's intent into navigation at the right moment, from a cold start, from the background, and after a Play install.

Step 1 of 5The shape of the problem

The shape of the problem

In a Compose app, the activity owns the intent and the NavHost owns navigation. A link can arrive before the first frame (cold start), while the app is open (onNewIntent), or seconds after the first launch, when the SDK finds the link a Play install carried. The third case is the one that catches people out: there is no intent at all, just an event that shows up later.

So the reliable pattern is: the SDK turns every one of those into a single stream of link events, and a small piece of state carries the next path into Compose, where a LaunchedEffect navigates once the NavHost exists.

Wiring it up

Create the client once in your Application, exactly as on the Android install page, with a background executor. Then, in the activity:

MainActivity.kt
class MainActivity : ComponentActivity() {
    private val links get() = (application as App).links
    private val nextPath = MutableStateFlow<String?>(null)

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        links.onLink { e -> if (e.matched) nextPath.value = e.path }   // runs on the SDK's executor
        if (savedInstanceState == null) links.start(intent?.dataString)
        setContent {
            val nav = rememberNavController()
            val path by nextPath.collectAsState()
            LaunchedEffect(path) {
                val p = path?.removePrefix("/") ?: return@LaunchedEffect
                runCatching { nav.navigate(p) }          // unknown path: stay where you are
                nextPath.value = null
            }
            NavHost(nav, startDestination = "home") {
                composable("home") { HomeScreen() }
                composable("product/{id}") { ProductScreen(it.arguments?.getString("id").orEmpty()) }
            }
        }
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        intent.dataString?.let(links::handleUrl)
    }
}

MutableStateFlow is safe to set from the SDK's thread, so there's no runOnUiThread here; Compose collects it on the main thread. onLink replays past events, so subscribing in onCreate doesn't miss the launch link.

Navigation Compose can match deep links by itself if a destination declares navDeepLink { uriPattern = … }, and NavHost reads the activity's intent to do it. If you declare patterns for your link domain too, a cold start can navigate twice: once from Navigation, once from the SDK. Leave link-domain patterns out and let the SDK's path drive navigation. Patterns for other URLs, like an OAuth callback, are fine.

Manifest notes for Compose apps

Use android:launchMode="singleTask" on the one activity, or a link tapped while the app is open starts a second copy and onNewIntent never runs. Keep both intent filters: the verified one for https://hilltop.strait.link and the custom-scheme one the browser hand-off uses. For typed routes (Navigation 2.8+ serializable classes), map the path to a route object in the LaunchedEffect instead of passing the string.

Checking it

adb shell am start -W -a android.intent.action.VIEW -d "yourapp://shop.example.com/product/42" should open ProductScreen with the app closed and with it in the background. adb shell pm get-app-links shows whether hilltop.strait.link is verified. For the install case, the Android test page walks through a deferred link from Google Play.

Open the Jetpack Compose (Kotlin) docs

Ship links that open your Jetpack Compose (Kotlin) app.

Free for 25,000 taps a month, no card. Every tap gets a trace you can read.