{"id":568,"date":"2026-03-22T09:00:00","date_gmt":"2026-03-22T14:00:00","guid":{"rendered":"https:\/\/tolinku.com\/blog\/?p=568"},"modified":"2026-03-07T03:48:17","modified_gmt":"2026-03-07T08:48:17","slug":"android-app-links-notifications","status":"publish","type":"post","link":"https:\/\/tolinku.com\/blog\/android-app-links-notifications\/","title":{"rendered":"Deep Linking from Android Notifications"},"content":{"rendered":"\n
Push notifications are one of the highest-value surfaces for deep linking. A notification about an order update, a new message, or a price drop is only useful if tapping it takes the user directly to the relevant screen. Yet notification deep links are implemented incorrectly more often than not: either the back stack is missing (pressing Back exits the app), the app state is ignored (the notification overwrites whatever the user was doing), or the deep link only works when the app is closed.<\/p>\n\n\n\n
This tutorial covers notification deep links properly, from PendingIntent<\/code> construction through back stack building, foreground and background handling, and testing.<\/p>\n\n\n\n
The Two Entry Points<\/h2>\n\n\n\n
When a user taps a notification, Android needs to know what to do. That instruction comes from the PendingIntent<\/code> you attach to the notification when building it. There are two approaches:<\/p>\n\n\n\n
Activity PendingIntent:<\/strong> Directly opens an Activity with an Intent. Simple, but you manage the back stack yourself.<\/p>\n\n\n\n
TaskStackBuilder PendingIntent:<\/strong> Builds a synthetic back stack from a list of Activities or Navigation destinations. This is the correct approach for deep links because it gives users a logical Back navigation experience.<\/p>\n\n\n\n
The correct choice for most deep link notifications is TaskStackBuilder<\/code>. Direct Activity intents leave users with no back stack, so pressing Back exits the app immediately.<\/p>\n\n\n\n
Setting Up Notification Channels<\/h2>\n\n\n\n
Android 8.0 (API 26) requires notification channels. Before building notifications, register channels during app initialization:<\/p>\n\n\n\n
object NotificationChannels {\n const val ORDERS = "orders"\n const val MESSAGES = "messages"\n const val PROMOTIONS = "promotions"\n\n fun createChannels(context: Context) {\n if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return\n\n val notificationManager =\n context.getSystemService(NotificationManager::class.java)\n\n val channels = listOf(\n NotificationChannel(\n ORDERS,\n "Order Updates",\n NotificationManager.IMPORTANCE_HIGH\n ).apply {\n description = "Updates about your orders"\n },\n NotificationChannel(\n MESSAGES,\n "Messages",\n NotificationManager.IMPORTANCE_DEFAULT\n ).apply {\n description = "New messages from other users"\n },\n NotificationChannel(\n PROMOTIONS,\n "Promotions",\n NotificationManager.IMPORTANCE_LOW\n ).apply {\n description = "Deals and promotional offers"\n }\n )\n\n channels.forEach { notificationManager.createNotificationChannel(it) }\n }\n}\n<\/code><\/pre>\n\n\n\n
Call NotificationChannels.createChannels(context)<\/code> in your Application.onCreate()<\/code>. Creating channels is idempotent, so calling it on every launch is safe.<\/p>\n\n\n\n
Building a Deep Link Notification with TaskStackBuilder<\/h2>\n\n\n\n
Here is a complete example for an order update notification that deep links to an order detail screen:<\/p>\n\n\n\n
fun buildOrderNotification(\n context: Context,\n orderId: String,\n statusText: String\n): Notification {\n\n \/\/ The destination intent: what screen to show when notification is tapped\n val destinationIntent = Intent(\n Intent.ACTION_VIEW,\n "https:\/\/yourdomain.com\/orders\/$orderId".toUri(),\n context,\n MainActivity::class.java\n )\n\n \/\/ TaskStackBuilder constructs the back stack\n val stackBuilder = TaskStackBuilder.create(context).apply {\n \/\/ Add the parent chain first\n addParentStack(MainActivity::class.java)\n \/\/ Add the destination on top\n addNextIntent(destinationIntent)\n }\n\n val pendingIntent = stackBuilder.getPendingIntent(\n orderId.hashCode(), \/\/ Unique request code per notification\n PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE\n )\n\n return NotificationCompat.Builder(context, NotificationChannels.ORDERS)\n .setSmallIcon(R.drawable.ic_notification)\n .setContentTitle("Order Update")\n .setContentText(statusText)\n .setAutoCancel(true)\n .setContentIntent(pendingIntent)\n .setPriority(NotificationCompat.PRIORITY_HIGH)\n .build()\n}\n<\/code><\/pre>\n\n\n\n
PendingIntent.FLAG_IMMUTABLE<\/code> is required for API 31 and above. FLAG_UPDATE_CURRENT<\/code> ensures that if a notification with the same request code already exists, the intent data is updated rather than a duplicate being created.<\/p>\n\n\n\n
The request code (orderId.hashCode()<\/code>) should be unique per notification. If you use the same request code for two different notifications, the second will overwrite the first's PendingIntent<\/code>.<\/p>\n\n\n\n
Using NavDeepLinkBuilder with Navigation Component<\/h2>\n\n\n\n
If your app uses the Jetpack Navigation component, NavDeepLinkBuilder<\/code> is cleaner than constructing intents manually. It understands your nav graph and builds the back stack from the graph structure automatically:<\/p>\n\n\n\n
NavDeepLinkBuilder<\/code> reads the nav graph to determine the parent destinations and constructs the back stack accordingly. The user arrives at orderDetailFragment<\/code> with homeFragment<\/code> (the graph's start destination) in the back stack. Pressing Back navigates to Home, not out of the app.<\/p>\n\n\n\n
If the destination is inside a nested graph, NavDeepLinkBuilder<\/code> includes the nested graph's start destination in the back stack as well.<\/p>\n\n\n\n
Handling Foreground vs Background App States<\/h2>\n\n\n\n
The behavior when a notification is tapped depends on whether your app is running in the foreground, in the background, or not running at all.<\/p>\n\n\n\n
App not running:<\/strong> Android creates a fresh task using your PendingIntent<\/code>. The back stack from TaskStackBuilder<\/code> or NavDeepLinkBuilder<\/code> is created as-is. This works correctly with both approaches.<\/p>\n\n\n\n
App in background:<\/strong> The system brings your existing task to the foreground. If you used TaskStackBuilder<\/code> with FLAG_UPDATE_CURRENT<\/code>, the destination intent's data is updated, and the Activity handles it. This depends on how your MainActivity<\/code> is configured.<\/p>\n\n\n\n
App in foreground:<\/strong> The user is actively using the app. Tapping the notification should not discard the current state. This is where things need attention.<\/p>\n\n\n\n
For a singleTop<\/code> or singleTask<\/code> launch mode Activity, the system calls onNewIntent<\/code> instead of creating a new instance. Handle this in your Activity:<\/p>\n\n\n\n
class MainActivity : AppCompatActivity() {\n\n override fun onCreate(savedInstanceState: Bundle?) {\n super.onCreate(savedInstanceState)\n \/\/ ...\n handleIntent(intent)\n }\n\n override fun onNewIntent(intent: Intent) {\n super.onNewIntent(intent)\n handleIntent(intent)\n }\n\n private fun handleIntent(intent: Intent) {\n intent.data?.let { uri ->\n navController.handleDeepLink(intent)\n }\n }\n}\n<\/code><\/pre>\n\n\n\n
With NavDeepLinkBuilder<\/code>, if the app is in the foreground, Navigation handles routing to the destination without destroying the current state. The destination is added to the current back stack rather than replacing it.<\/p>\n\n\n\n
Notification Deep Links with Custom Data<\/h2>\n\n\n\n
Sometimes you want to pass extra data with the notification beyond what fits in the URL. For example, a notification might include a thumbnail URL for display that does not belong in the deep link URI.<\/p>\n\n\n\n
Pass extra data through the Intent extras, then read them in your Activity or Fragment:<\/p>\n\n\n\n
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {\n super.onViewCreated(view, savedInstanceState)\n\n val orderId = args.orderId \/\/ From Navigation safe args\n val thumbnailUrl = activity?.intent?.getStringExtra("thumbnail_url")\n\n viewModel.loadOrder(orderId, thumbnailUrl)\n}\n<\/code><\/pre>\n\n\n\n
Be careful with extras when using NavDeepLinkBuilder<\/code>: extras passed to the builder are added to the PendingIntent<\/code> extras, but Navigation uses the Bundle passed to setArguments()<\/code> for navigation arguments. Keep navigation arguments in the Bundle and supplementary data in extras.<\/p>\n\n\n\n
Handling Notification Deep Links in BroadcastReceiver<\/h2>\n\n\n\n
Some notification actions (like dismissing, replying, or button taps) route through a BroadcastReceiver<\/code> rather than directly to an Activity. If you need to navigate after receiving a broadcast, you have to start the Activity from the receiver:<\/p>\n\n\n\n
class NotificationActionReceiver : BroadcastReceiver() {\n\n override fun onReceive(context: Context, intent: Intent) {\n val orderId = intent.getStringExtra("order_id") ?: return\n val action = intent.getStringExtra("action") ?: return\n\n when (action) {\n "MARK_RECEIVED" -> {\n \/\/ Handle the action\n OrderRepository.markReceived(orderId)\n\n \/\/ Navigate to confirmation\n val launchIntent = NavDeepLinkBuilder(context)\n .setGraph(R.navigation.nav_graph)\n .setDestination(R.id.orderConfirmationFragment)\n .setArguments(bundleOf("orderId" to orderId))\n .createTaskStackBuilder()\n .getPendingIntent(\n orderId.hashCode(),\n PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE\n )\n\n launchIntent?.send()\n }\n }\n }\n}\n<\/code><\/pre>\n\n\n\n
Note that BroadcastReceiver.onReceive<\/code> is called on the main thread with a limited execution window. Do not perform long-running operations here. If you need async work (like a network call) before navigating, use goAsync()<\/code> to extend the receiver's lifetime or dispatch the work to a WorkManager<\/code> task.<\/p>\n\n\n\n
Notification Permission on Android 13 and Later<\/h2>\n\n\n\n
Android 13 (API 33) added a runtime permission for notifications: POST_NOTIFICATIONS<\/code>. Apps targeting API 33 or higher must request this permission before posting notifications.<\/p>\n\n\n\n
\/\/ Check and request notification permission\nif (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {\n when {\n ContextCompat.checkSelfPermission(\n this,\n Manifest.permission.POST_NOTIFICATIONS\n ) == PackageManager.PERMISSION_GRANTED -> {\n \/\/ Permission granted, can post notifications\n }\n shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS) -> {\n \/\/ Show rationale then request\n showNotificationPermissionRationale()\n }\n else -> {\n requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)\n }\n }\n}\n<\/code><\/pre>\n\n\n\n
Without this permission on API 33+ devices, your notifications will be silently dropped. The deep link code is correct, but the notification never appears.<\/p>\n\n\n\n
Declare the permission in your manifest:<\/p>\n\n\n\n
![\"Close-up](\"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/android-app-links-notifications-inline-2.jpg\")