In Navigation Compose, how does a product URL opened from outside the app reach a composable<ProductDetail> destination through navDeepLink, and which back stack does the user get?
answer
- deepLinks on the destination
- basePath plus the route's arguments
- the manifest is on you
- onNewIntent with a reused activity
- start destinations stacked underneath
basics
~20 sAdd navDeepLink<ProductDetail>(basePath = ...) to the destination's deepLinks and a matching intent filter in the manifest. NavController matches the intent's URI; in a new task it builds the back stack from the start destination of each enclosing graph.
solid answer
~40 sIn Navigation Compose you add `deepLinks = listOf(navDeepLink<ProductDetail>(basePath = "https://shop.example.com/product"))` to `composable<ProductDetail>`; Navigation appends the route's arguments to the base path, so a required `id` becomes `/product/{id}`. A programmatic graph cannot generate manifest entries, so you add the matching `<intent-filter>` to the activity yourself. When the activity is created with the intent, the `NavController` calls `handleDeepLink()` once the graph is set; if the activity is reused (`singleTop`, `singleTask`), you must call `navController.handleDeepLink(intent)` in `onNewIntent`. With `FLAG_ACTIVITY_NEW_TASK` the back stack is replaced: the start destination of every enclosing graph is stacked under ProductDetail, so Back goes Home. Without the flag the user stays in the caller's task, and Back returns there.
code
kotlin · 18 linesclass MainActivity : ComponentActivity() {
private var navController: NavHostController? = null
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContent {
val controller = rememberNavController()
navController = controller
ShopNavHost(controller)
}
}
// Needed only when the activity is reused, e.g. launchMode="singleTop".
override fun onNewIntent(intent: Intent) {
super.onNewIntent(intent)
navController?.handleDeepLink(intent)
}
}go deeper
Recall that a destination lists its deep links with navDeepLink and that the activity also needs an intent filter in the manifest.
Explain how navDeepLink builds the pattern from the route class, why Compose graphs need hand-written intent filters, and when handleDeepLink must be called manually.
Diagnose links that open the wrong screen or fail when the app is running, and shape nested graphs so the synthetic back stack sends Back where users expect.
Decide which destinations a team exposes as links and how nested graph structure is reviewed, since it fixes the back stack of every external entry.
## Two halves: Navigation and the manifest A **deep link** takes the user straight to a destination inside the app. For a link such as `https://shop.example.com/product/p-42` to open a product detail screen, two things must be true: 1. **Android must route the intent to your activity.** That is the manifest's job: an `<intent-filter>` with `ACTION_VIEW`, the `DEFAULT` and `BROWSABLE` categories and a `<data>` element for the scheme and host. 2. **The `NavController` must match the URI to a destination.** That is Navigation's job, driven by the `NavDeepLink`s you attach to destinations. With XML graphs, a `<nav-graph>` element in the manifest makes the build generate the intent filters. **A Navigation Compose graph is built at runtime, so Navigation cannot generate them**: you write the `<intent-filter>` by hand. Verifying that you own the domain for App Links is a manifest and platform concern covered with intents and intent filters. ## Declaring the deep link on the destination ```kotlin @Serializable data class ProductDetail(val id: String) composable<ProductDetail>( deepLinks = listOf( navDeepLink<ProductDetail>(basePath = "https://shop.example.com/product") ) ) { entry -> ProductDetailScreen(entry.toRoute<ProductDetail>().id) } ``` `navDeepLink<T>(basePath)` reads the route class and **appends its arguments to the base path**: required arguments as path segments, arguments with defaults as query parameters. The pattern here is `https://shop.example.com/product/{id}`. Matching rules worth knowing: - query parameters for arguments with a default or nullable value need not appear; - extra query parameters in the incoming URI do not prevent a match; - a deep link can also match an action or MIME type; URI matching is tried first. ## When the intent is handled | Situation | What happens | |---|---| | Activity created by the intent (standard launch mode) | the `NavController` calls `handleDeepLink()` itself the first time its graph is set | | Activity reused (`singleTop`, `singleTask`) | the intent arrives in `onNewIntent`; you must call `navController.handleDeepLink(intent)` | The guide recommends the default `standard` launch mode with Navigation for this reason. **Navigation 2.10.0** changed `handleDeepLink` so that only recognized deep links are handled and all others are ignored; if a link stops working after that upgrade, the release notes advise defining it as a deep link in the navigation graph. ## The back stack the user gets This is the part interviews probe: 1. **With `FLAG_ACTIVITY_NEW_TASK`** (typical when a browser or another app launches you): the task's back stack is cleared and replaced with the deep link destination, and **the start destination of each enclosing graph is added beneath it**. If ProductDetail sits in a `CatalogGraph` nested in the root graph, the stack is Home (root start) -> Catalog (catalog graph start) -> ProductDetail. Back then walks up as if the user had entered from the launcher. 2. **Without the flag**: the app stays on the task of the app that fired the intent. Back returns to that app; Up starts your app's own task on the destination's parent in the graph. So the shape of your nested graphs is the shape of the synthetic back stack. Put ProductDetail in a graph whose start destination is where Back should lead. ## Links from inside the app - **Notifications and widgets** use an *explicit* deep link: a `PendingIntent`. For a programmatic graph the guide recommends `TaskStackBuilder` with `addNextIntentWithParentStack` over building the whole graph in a background component; the task is cleared and the same start-destination stack is built. - **In-app navigation by URI**: `navController.navigate(uri)` or `navigate(NavDeepLinkRequest)` goes to any matching destination **without resetting the back stack**; `popUpTo` still applies. ## Failure modes - The link opens the app's start screen instead of the product: the manifest filter matched, but no `NavDeepLink` pattern did. Check the base path and that required arguments are in the URI. - The link works on cold start but not when the app is open: a non-standard launch mode with no `handleDeepLink` in `onNewIntent`. - Back from a deep-linked screen exits the app unexpectedly: the destination sits in a graph whose start destinations do not build the stack you want. What stack a shared link *should* build and how auth gates apply are design questions covered in the mobile system design material on navigation and entry points.
- A product link works on a cold start but does nothing when the shopping app is already open. What is the likely cause in Navigation Compose?The activity uses a non-standard launch mode such as `singleTop`, so Android delivers the link to the existing instance through `onNewIntent` instead of creating a new one. The `NavController` handles the intent automatically only when its graph is first set. Override `onNewIntent` and call `navController.handleDeepLink(intent)`, or keep the default `standard` launch mode.
- How does navigating in-app with navController.navigate(uri) differ from an external deep link in Navigation Compose?An in-app `navigate(Uri)` or `navigate(NavDeepLinkRequest)` finds the destination whose deep link matches and pushes it onto the current back stack; it does not clear the stack or add the start destinations of enclosing graphs. `popUpTo` still works if you pass it. An external link launched with `FLAG_ACTIVITY_NEW_TASK` replaces the stack instead.
- Navigation Compose generates the intent filters from deepLinks automatically
- Deep links are handled automatically even when the activity is reused via onNewIntent
- A deep link always opens the destination alone, so Back exits the app
- navDeepLink needs the full URI pattern including every argument placeholder
- navigate(uri) from inside the app clears the back stack like an external link
Assumes Navigation Compose 2.10.2 with Compose 1.12; Navigation 2.10.0 made handleDeepLink ignore deep links it does not recognize, and navDeepLink<T>(basePath) exists since 2.8.0.