Day 12: Deep Linking on Android
Lesson 12 — Deep Linking on Android
NomadAir Masterclass · Module 2 · Beginner
The Naive Flutter Approach — And Why It Breaks
Deep linking is the invisible infrastructure underneath every push notification in a travel app. When Cleartrip sends "Your BOM→DXB flight price dropped to ₹14,200!", the user taps it. If the link opens to the app's home screen — not to the specific flight — the user has to search again. Two taps later, if the price has already expired, they abandon the session. The notification was a liability, not a conversion.
The naive implementation is to handle deep links as an afterthought: add a getInitialUri call somewhere in main.dart, parse the URL string with a switch statement, and push the appropriate route. This breaks in four places:
Failure mode 1: Cold start. The app is not running. Android launches it via the intent filter. The Flutter engine starts, main() runs, MaterialApp builds with home: DiscoveryScreen(), and then the app processes the deep link. But MaterialApp.home has already committed to DiscoveryScreen. Navigating from it to the booking detail requires pushing on top of the home screen — the back stack is wrong.
Failure mode 2: Warm start. The app is backgrounded. Android brings it to the foreground via the intent filter. If you are using GoRouter.initialLocation, the existing route tree is preserved. If you are using Navigator.pushNamed, the existing back stack receives the push, which may or may not be the right context.
Failure mode 3: Unknown route graceful handling. A deep link to nomadair://booking/EXPIRED-123 should not crash. It should show a friendly "This booking is no longer available" message. Without the errorBuilder from Lesson 11 and a structured route parameter validation layer, it crashes.
Failure mode 4: AndroidManifest.xml misconfiguration. The intent filter must have the exact combination of scheme, host, pathPrefix, and action attributes, or Android simply ignores the link. One missing attribute means zero deep links work, and the failure is silent — Android silently falls back to opening a browser.
What Android Is Actually Doing
When a URL matching the intent filter pattern is tapped, Android consults the intent filter registry and finds NomadAir as a handler. It constructs an Intent with ACTION_VIEW and the URL as data, and delivers it to the registered Activity — Flutter's FlutterActivity.
FlutterActivity receives the intent in onCreate (cold start) or onNewIntent (warm start, because launchMode="singleTop" means Android reuses the existing activity instance). Flutter's SystemChannels.navigation channel delivers the initial route string to the Dart side, where GoRouter reads it as its initialLocation.
The critical Android launchMode configuration is singleTop. Without it, Android creates a new FlutterActivity instance for every deep link tap, even if the app is already open — resulting in multiple instances of the app running simultaneously, each with its own state. singleTop ensures that when the app is already in the foreground, the existing instance receives onNewIntent rather than being duplicated.
GoRouter reads SystemChannels.navigation.setMockMethodCallHandler during testing to inject deep link URLs, which is how the DeepLinkExplorer in this lesson simulates both cold start and warm start scenarios without requiring an actual ADB shell command during automated testing.
Keep going with the full lesson
The rest of this lesson — plus its implementation guide, runnable scripts and source code — is included with the course or an All Access plan. Create a free account to start the free lessons in every course.
Already a member? Sign in