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.
- Guide
- Android
strait-sdk-android- Faster: one prompt
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:
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.
Don't let navDeepLink compete
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.
Docs for this setup
Where to go next for Jetpack Compose (Kotlin)
Check your setup
Free tools for the parts that usually break
Other guides: Expo · Next.js · FlutterFlow · Capacitor and Ionic · SwiftUI · Unity
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.