The Jetpack Navigation component handles the mechanics of fragment transactions, back stack management, and argument passing. It also has first-class support for deep links, which means you can define your URL patterns in the nav graph XML and let Navigation handle routing rather than writing manual intent parsing code.<\/p>\n\n\n\n
This tutorial walks through setting up deep links with the Navigation component from scratch, covering the nav graph definitions, Activity setup, argument passing, nested graphs, and testing. It assumes you have already verified your App Links (the Add the Navigation component dependencies to your The Navigation component uses a nav graph XML file to define your destinations and the connections between them. Create one at A deep link in the nav graph is declared as a child element of a destination. This is called an implicit deep link because it maps incoming URLs to destinations without code.<\/p>\n\n\n\n The Note the Your Activity needs to connect the NavController to incoming intents. Add the nav graph to your The In your Activity:<\/p>\n\n\n\n The When the Navigation component routes a deep link to a destination, it parses the URL arguments and passes them as a navigation Bundle. Access them in your Fragment using the Safe Args generated class or the arguments Bundle directly.<\/p>\n\n\n\n With Safe Args (recommended):<\/p>\n\n\n\n Safe Args generates Without Safe Args, access arguments directly:<\/p>\n\n\n\n Real apps often have nested navigation graphs, for example a checkout flow that is a separate graph from the main navigation. Deep links work with nested graphs, but require care.<\/p>\n\n\n\n Define a nested graph:<\/p>\n\n\n\n Deep links defined in nested graph destinations work correctly. The Navigation component builds the back stack from the nested graph's start destination, so pressing Back from a deep-linked destination within the checkout flow navigates to The back stack behavior for deep links differs from standard navigation. When a user arrives via a deep link, Navigation builds the back stack from the start destination of the graph to the linked destination. This means:<\/p>\n\n\n\n This is the correct behavior: the user can always navigate back to a logical parent. Without this, pressing Back after a deep link would exit the app entirely.<\/p>\n\n\n\n To customize the back stack for a specific deep link, use the Sometimes you need to navigate to a deep link destination programmatically, for example after processing a push notification payload or after an async validation step.<\/p>\n\n\n\n Use This is equivalent to the user clicking the URL but triggers the navigation within your app without needing an actual Intent. The nav graph is consulted to match the URI to a destination, and arguments are extracted from the URI the same way.<\/p>\n\n\n\n You can also navigate directly to a destination using the generated directions class:<\/p>\n\n\n\n The programmatic approach is useful when you receive a deep link URI from a notification or from your own deferred linking logic, and want to route the user after your app is already running.<\/p>\n\n\n\n The Navigation component distinguishes between two types:<\/p>\n\n\n\n Implicit deep links<\/strong> are URI patterns defined in the nav graph, handled by Android when the user clicks a link from outside the app (email, SMS, browser, etc.). These are what the Explicit deep links<\/strong> are Explicit deep links build a complete back stack automatically, just like implicit deep links. When the user taps the notification and the Navigation component provides a test artifact for instrumented tests:<\/p>\n\n\n\n Use For testing the full deep link entry from an external intent, use Navigation's URI matching has some nuances worth knowing:<\/p>\n\n\n\n Query parameters are optional by default.<\/strong> If you define Path parameters are required.<\/strong> No wildcard matching.<\/strong> You cannot use Scheme is part of matching.<\/strong> For apps with complex URL structures, Navigation's matching may not cover every case. In those situations, combining Navigation's implicit deep link handling for simple cases with custom logic in The The nav-graph element adds unverified intent filters that handle the routing. The explicit assetlinks.json<\/code> file is in place and Android has confirmed the association). If not, start with our Android App Links developer documentation<\/a> first.<\/p>\n\n\n\nProject Setup<\/h2>\n\n\n\n
build.gradle<\/code>:<\/p>\n\n\n\ndependencies {\n val navVersion = "2.7.7"\n implementation("androidx.navigation:navigation-fragment-ktx:$navVersion")\n implementation("androidx.navigation:navigation-ui-ktx:$navVersion")\n}\n<\/code><\/pre>\n\n\n\nres\/navigation\/nav_graph.xml<\/code> if you do not already have one.<\/p>\n\n\n\nDefining Deep Links in the Nav Graph<\/h2>\n\n\n\n
<?xml version="1.0" encoding="utf-8"?>\n<navigation\n xmlns:android="http:\/\/schemas.android.com\/apk\/res\/android"\n xmlns:app="http:\/\/schemas.android.com\/apk\/res-auto"\n android:id="@+id\/nav_graph"\n app:startDestination="@id\/homeFragment">\n\n <fragment\n android:id="@+id\/homeFragment"\n android:name="com.example.app.HomeFragment"\n android:label="Home" \/>\n\n <fragment\n android:id="@+id\/productDetailFragment"\n android:name="com.example.app.ProductDetailFragment"\n android:label="Product">\n\n <argument\n android:name="productId"\n app:argType="string" \/>\n\n <deepLink\n android:id="@+id\/productDeepLink"\n app:uri="https:\/\/yourdomain.com\/products\/{productId}" \/>\n <\/fragment>\n\n <fragment\n android:id="@+id\/checkoutFragment"\n android:name="com.example.app.CheckoutFragment"\n android:label="Checkout">\n\n <argument\n android:name="cartToken"\n app:argType="string" \/>\n\n <argument\n android:name="promoCode"\n app:argType="string"\n android:defaultValue="" \/>\n\n <deepLink\n android:id="@+id\/checkoutDeepLink"\n app:uri="https:\/\/yourdomain.com\/checkout?token={cartToken}&promo={promoCode}" \/>\n <\/fragment>\n\n<\/navigation>\n<\/code><\/pre>\n\n\n\n{productId}<\/code> syntax in the URI template is a placeholder. Navigation extracts the value from the actual URL and passes it as a navigation argument with the same name. For path parameters like \/products\/{productId}<\/code>, the value is extracted from the URL path. For query parameters like ?token={cartToken}<\/code>, the value is extracted from the query string.<\/p>\n\n\n\n&<\/code> encoding for &<\/code> in XML. This is required in XML attribute values.<\/p>\n\n\n\nActivity Setup<\/h2>\n\n\n\n
AndroidManifest.xml<\/code>:<\/p>\n\n\n\n<activity android:name=".MainActivity">\n <nav-graph android:value="@navigation\/nav_graph" \/>\n\n <intent-filter>\n <action android:name="android.intent.action.MAIN" \/>\n <category android:name="android.intent.category.LAUNCHER" \/>\n <\/intent-filter>\n<\/activity>\n<\/code><\/pre>\n\n\n\n<nav-graph><\/code> element tells the build system to read your nav graph and generate the corresponding <intent-filter><\/code> entries in the manifest automatically at build time. You do not need to write the intent filters by hand. This is a significant advantage of using Navigation's deep link support.<\/p>\n\n\n\nclass MainActivity : AppCompatActivity() {\n\n private lateinit var navController: NavController\n\n override fun onCreate(savedInstanceState: Bundle?) {\n super.onCreate(savedInstanceState)\n setContentView(R.layout.activity_main)\n\n val navHostFragment = supportFragmentManager\n .findFragmentById(R.id.nav_host_fragment) as NavHostFragment\n navController = navHostFragment.navController\n\n \/\/ Navigation component handles deep link routing automatically\n \/\/ when activity is launched with a matching intent\n }\n\n override fun onNewIntent(intent: Intent) {\n super.onNewIntent(intent)\n navController.handleDeepLink(intent)\n }\n}\n<\/code><\/pre>\n\n\n\nnavController.handleDeepLink(intent)<\/code> call in onNewIntent<\/code> is important. When your app is already running and the user clicks a deep link (with android:launchMode="singleTop"<\/code> or singleTask<\/code>), the Activity receives onNewIntent<\/code> rather than re-creating. Without this call, the navigation would not happen.<\/p>\n\n\n\nAccessing Arguments in Fragments<\/h2>\n\n\n\n
class ProductDetailFragment : Fragment() {\n\n private val args: ProductDetailFragmentArgs by navArgs()\n\n override fun onViewCreated(view: View, savedInstanceState: Bundle?) {\n super.onViewCreated(view, savedInstanceState)\n\n val productId = args.productId\n viewModel.loadProduct(productId)\n }\n}\n<\/code><\/pre>\n\n\n\nProductDetailFragmentArgs<\/code> from your nav graph arguments, giving you type-safe access. To enable Safe Args, add the plugin to your build.gradle<\/code>:<\/p>\n\n\n\n\/\/ build.gradle (app)\nplugins {\n id("androidx.navigation.safeargs.kotlin")\n}\n<\/code><\/pre>\n\n\n\n\/\/ build.gradle (project)\nbuildscript {\n dependencies {\n classpath("androidx.navigation:navigation-safe-args-gradle-plugin:2.7.7")\n }\n}\n<\/code><\/pre>\n\n\n\nval productId = arguments?.getString("productId") ?: return\n<\/code><\/pre>\n\n\n\nNested Navigation Graphs<\/h2>\n\n\n\n
<navigation\n android:id="@+id\/nav_graph"\n app:startDestination="@id\/homeFragment">\n\n <fragment\n android:id="@+id\/homeFragment"\n android:name="com.example.app.HomeFragment" \/>\n\n <navigation\n android:id="@+id\/checkout_graph"\n app:startDestination="@id\/checkoutFragment">\n\n <fragment\n android:id="@+id\/checkoutFragment"\n android:name="com.example.app.CheckoutFragment">\n <argument\n android:name="cartToken"\n app:argType="string" \/>\n <deepLink\n app:uri="https:\/\/yourdomain.com\/checkout\/{cartToken}" \/>\n <\/fragment>\n\n <fragment\n android:id="@+id\/paymentFragment"\n android:name="com.example.app.PaymentFragment" \/>\n\n <fragment\n android:id="@+id\/confirmationFragment"\n android:name="com.example.app.ConfirmationFragment">\n <argument\n android:name="orderId"\n app:argType="string" \/>\n <deepLink\n app:uri="https:\/\/yourdomain.com\/orders\/{orderId}" \/>\n <\/fragment>\n\n <\/navigation>\n\n<\/navigation>\n<\/code><\/pre>\n\n\n\ncheckoutFragment<\/code> rather than exiting the app.<\/p>\n\n\n\nBack Stack Construction<\/h2>\n\n\n\n
\n
https:\/\/yourdomain.com\/products\/123<\/code><\/li>\nproductDetailFragment<\/code><\/li>\nhomeFragment<\/code> -> productDetailFragment<\/code><\/li>\nhomeFragment<\/code><\/li>\napp:action<\/code> attribute on the deep link element to reference an action with popUpTo<\/code> configuration:<\/p>\n\n\n\n<deepLink\n app:uri="https:\/\/yourdomain.com\/products\/{productId}"\n app:action="@id\/action_to_product_detail" \/>\n\n<action\n android:id="@+id\/action_to_product_detail"\n app:destination="@id\/productDetailFragment"\n app:popUpTo="@id\/homeFragment"\n app:popUpToInclusive="false" \/>\n<\/code><\/pre>\n\n\n\nHandling Deep Links Programmatically<\/h2>\n\n\n\n
NavDeepLinkRequest<\/code>:<\/p>\n\n\n\nval request = NavDeepLinkRequest.Builder\n .fromUri("https:\/\/yourdomain.com\/products\/abc123".toUri())\n .build()\n\nnavController.navigate(request)\n<\/code><\/pre>\n\n\n\n\/\/ Equivalent, bypasses URI matching, goes directly to destination\nnavController.navigate(\n NavGraphDirections.actionToProductDetail("abc123")\n)\n<\/code><\/pre>\n\n\n\nImplicit vs Explicit Deep Links<\/h2>\n\n\n\n
<deepLink><\/code> element in the nav graph configures.<\/p>\n\n\n\nPendingIntent<\/code> objects that navigate to a specific destination when triggered. These are typically used in notifications. They are constructed with NavDeepLinkBuilder<\/code>:<\/p>\n\n\n\nval pendingIntent = NavDeepLinkBuilder(context)\n .setGraph(R.navigation.nav_graph)\n .setDestination(R.id.productDetailFragment)\n .setArguments(bundleOf("productId" to "abc123"))\n .createPendingIntent()\n<\/code><\/pre>\n\n\n\nPendingIntent<\/code> fires, they land in the correct destination with the correct back stack. For a full treatment of notification deep links, see our article on deep linking from Android notifications<\/a>.<\/p>\n\n\n\nTesting Navigation Deep Links<\/h2>\n\n\n\n
\/\/ build.gradle\nandroidTestImplementation("androidx.navigation:navigation-testing:2.7.7")\n<\/code><\/pre>\n\n\n\nTestNavHostController<\/code> to verify navigation without running on a real device:<\/p>\n\n\n\n@Test\nfun deepLinkNavigatesToProductDetail() {\n val navController = TestNavHostController(ApplicationProvider.getApplicationContext())\n\n val scenario = launchFragmentInContainer<HomeFragment>()\n scenario.onFragment { fragment ->\n navController.setGraph(R.navigation.nav_graph)\n Navigation.setViewNavController(fragment.requireView(), navController)\n }\n\n \/\/ Simulate deep link navigation\n val request = NavDeepLinkRequest.Builder\n .fromUri("https:\/\/yourdomain.com\/products\/test123".toUri())\n .build()\n\n scenario.onFragment {\n navController.navigate(request)\n }\n\n \/\/ Verify navigation happened\n assertThat(navController.currentDestination?.id).isEqualTo(R.id.productDetailFragment)\n}\n<\/code><\/pre>\n\n\n\nActivityScenario<\/code>:<\/p>\n\n\n\n@Test\nfun externalDeepLinkOpensProductDetail() {\n val intent = Intent(\n Intent.ACTION_VIEW,\n "https:\/\/yourdomain.com\/products\/test123".toUri()\n ).apply {\n setPackage(ApplicationProvider.getApplicationContext<Context>().packageName)\n }\n\n val scenario = ActivityScenario.launch<MainActivity>(intent)\n scenario.onActivity { activity ->\n val navController = activity.findNavController(R.id.nav_host_fragment)\n assertThat(navController.currentDestination?.id).isEqualTo(R.id.productDetailFragment)\n }\n}\n<\/code><\/pre>\n\n\n\nURL Matching Behavior<\/h2>\n\n\n\n
app:uri="https:\/\/yourdomain.com\/search?q={query}"<\/code>, the deep link matches URLs both with and without the ?q=<\/code> parameter. If the parameter is absent, the argument receives its default value.<\/p>\n\n\n\nhttps:\/\/yourdomain.com\/products\/{productId}<\/code> will not match https:\/\/yourdomain.com\/products\/<\/code>.<\/p>\n\n\n\n*<\/code> in URI templates. Each path segment must be a literal or a named parameter.<\/p>\n\n\n\nhttps:\/\/yourdomain.com\/products\/{id}<\/code> matches only HTTPS URLs, not HTTP or custom scheme URLs. Define separate deep link elements for each scheme you want to handle.<\/p>\n\n\n\nonNewIntent<\/code> for complex cases is a reasonable approach.<\/p>\n\n\n\nCombining with App Links Configuration<\/h2>\n\n\n\n
<nav-graph><\/code> element in the manifest generates intent filters automatically, but it does not add android:autoVerify="true"<\/code>. You need to either add that manually to the generated intent filters or add your own explicit intent filter alongside the nav-graph element:<\/p>\n\n\n\n<activity android:name=".MainActivity">\n <nav-graph android:value="@navigation\/nav_graph" \/>\n\n <!-- Explicit verified intent filter for App Links -->\n <intent-filter android:autoVerify="true">\n <action android:name="android.intent.action.VIEW" \/>\n <category android:name="android.intent.category.DEFAULT" \/>\n <category android:name="android.intent.category.BROWSABLE" \/>\n <data android:scheme="https" android:host="yourdomain.com" \/>\n <\/intent-filter>\n<\/activity>\n<\/code><\/pre>\n\n\n\nandroid:autoVerify="true"<\/code> filter handles the verification. Both are needed for full App Link behavior.<\/p>\n\n\n\n