Marketing sent the email. The link opened the app store instead of the promo screen. Support tickets mentioned "the link worked on Android but not iPhone." QA could reproduce it only on a physical device, never in the simulator.

If you are new to Flutter deep linking, that story probably sounds familiar.

What is a deep link? A URL that opens your app and navigates to a specific screen, not just the home screen. Example: https://example.com/promo/123 should open your app directly on the promo details page.

Why beginners struggle: three separate systems must agree before that works:

1. Your website (verification files that prove you own the domain)
2. iOS or Android native config (entitlements, manifest entries)
3. Your Flutter router (Dart code that maps the URL path to a screen)

Deep links look simple in a demo. In production, one misconfigured file fails silently.

We ship cross-platform mobile delivery with Flutter teams who need email, SMS, web, and ad campaigns to land on the right in-app screen. This post is the checklist we run before calling deep links done, with definitions for terms tutorials often skip. For platform behavior and Router vs Navigator handling, start with Flutter's Deep linking overview.

How a deep link works (mental model)

When someone taps a link, this is the flow:

1. User taps https://example.com/promo/123 in email, SMS, or a browser.
2. Phone checks whether your app is allowed to handle that domain (verification files on your server + native app config).
3. OS opens the app (if installed and verified) and passes the full URL to Flutter.
4. Your router reads the path (/promo/123) and shows the matching screen.

Two terms you will see everywhere:

• Cold start: the app was fully closed. The OS launches it and delivers the link shortly after.
• Warm start: the app was in the background. The OS wakes it and passes a new link while it is already running.

Cold start is where most beginner bugs hide (auth not ready, router not listening yet).

Terms you'll see in every tutorial

Official setup guides for each platform are in References at the end.

When Deep Links Matter (And When They Do Not)

You do not need deep links on day one of every app. Add them when a URL in email, SMS, or ads should land on a specific in-app screen.

Worth the setup cost:

• Passwordless login or magic links (login email opens the app to the confirm screen)
• Referral and invite flows (friend's invite link opens signup with code pre-filled)
• Push notification taps to specific content (notification opens the order detail screen)
• Email campaigns to product screens (newsletter link opens the sale page in-app)
• Web-to-app handoff from marketing sites (landing page link opens the app if installed)

Often overbuilt early:

• Every blog URL mapping to an in-app WebView
• Complex deferred deep linking before v1 has retention data
• Custom URL schemes as the only path (see below)

Scope the first release. Ship Universal Links / App Links for two or three high-value paths, then expand.

Custom Schemes vs Universal / App Links

If you are new to Flutter deep linking, start with verified HTTPS links on a domain you own.

Production default: HTTPS links on a domain you control, with platform verification files served correctly. Keep a custom scheme only as fallback for legacy campaigns if needed.

Beginner recommendation: prototype with a custom scheme locally if that helps you learn routing. Ship real campaigns with Universal Links / App Links.

Platform setup walkthroughs: Set up universal links for iOS and Set up app links for Android.

iOS: Universal Links Checklist

Associated Domains entitlement

In plain terms: tells iOS "this app is allowed to open links from example.com."

Where to click in Xcode: Runner target → Signing & Capabilities → Associated Domains → add entries like (see Apple's Supporting associated domains for entitlement and CDN details):

applinks:example.com
applinks:www.example.com

Match every host you use in marketing links. Missing www variants break half your campaigns.

apple-app-site-association (AASA)

In plain terms: a JSON file on your server that proves you own the domain and lists which app may open which paths.

Host at:

https://example.com/.well-known/apple-app-site-association

Requirements:

• Served over HTTPS
• No redirects on the AASA URL (common production bug)
• Content-Type preferably application/json (Apple is tolerant but avoid text/html error pages)
• Include correct appID (Team ID + bundle identifier) and paths array

Validate with Apple's CDN cache tool or third-party AASA validators after every deploy. File format and in-app handling: Supporting universal links in your app.

Flutter handling

In plain terms: Dart code that receives the URL from iOS and calls your router to show the right screen.

Packages commonly used: app_links, uni_links (legacy), or routing packages with link APIs (go_router deep link support). See Flutter's Deep linking for default handler behavior.

If you use a third-party link plugin, opt out of Flutter's built-in handler: set FlutterDeepLinkingEnabled to NO in Info.plist. Otherwise both handlers may fire and cause double navigation.

Pattern:

1. Listen for initial link on cold start (getInitialLink)
2. Subscribe to stream for warm start (uriLinkStream)
3. Parse path and query params
4. Navigate via your router (go_router, auto_route, etc.)

Cold start race: routing may run before auth state loads. Queue the pending deep link until session is ready, then navigate once.

Android: App Links Checklist

Intent filters in AndroidManifest.xml

In plain terms: tell Android which URLs should open your app instead of the browser.

Where to edit: android/app/src/main/AndroidManifest.xml, inside the <activity> tag for .MainActivity.

For verified App Links, use android:autoVerify="true" on intent filters with https scheme, host, and pathPrefix or pathPattern (see Set up app links for Android).

Example concept (adjust to your package):

<intent-filter android:autoVerify="true">
 <action android:name="android.intent.action.VIEW" />
 <category android:name="android.intent.category.DEFAULT" />
 <category android:name="android.intent.category.BROWSABLE" />
 <data android:scheme="https" android:host="example.com" android:pathPrefix="/promo" />
</intent-filter>

assetlinks.json

In plain terms: proves your app is the official handler for URLs on your domain.

Host at:

https://example.com/.well-known/assetlinks.json

Include SHA-256 cert fingerprints for release and upload keys. If this is your first Play Store release, get the SHA-256 from Play Console → App integrity, not your local debug key. Play App Signing uses Google-held keys; fetch fingerprints from Play Console. Format and hosting rules: Configure assetlinks.json.

Run (see Verify Android App Links):

adb shell pm get-app-links com.example.app

In plain terms: this command shows whether Android trusts your app for that domain. Confirm verified status on a release build, not debug-only.

Flutter parity

Same listener pattern as iOS. If you use a third-party link plugin, set flutter_deeplinking_enabled to false in AndroidManifest.xml (same opt-out as FlutterDeepLinkingEnabled on iOS). Test on physical devices: emulators miss many intent resolution edge cases.

Flutter Router Integration (go_router Example)

The incoming URL path must match a route you defined in Dart. Example: URL https://example.com/promo/123 → path /promo/123 → route /promo/:id → PromoScreen.

Conceptual flow with go_router:

final router = GoRouter(
 routes: [
 GoRoute(path: '/', builder: (_, __) => const HomeScreen()),
 GoRoute(path: '/promo/:id', builder: (_, state) {
 final id = state.pathParameters['id']!; // path from https://example.com/promo/123
 return PromoScreen(id: id);
 }),
 ],
);

Wire incoming URIs to router.go('/promo/$id') or equivalent after normalizing host and path. Official cookbooks use go_router; see the go_router deep linking topic.

Normalize paths: marketing may send trailing slashes, UTM query strings, or mixed casing. Strip tracking params before route matching.

Guard routes: if /account/orders/:id requires login, redirect to sign-in with return path stored, then resume after auth.

Backend and Web Fallback URLs

Deep links often start on the web. Plan three outcomes:

1. App installed: open app to target screen (Universal / App Link)
2. App not installed: show mobile web equivalent or store landing page
3. Desktop click: responsive web page, not a broken custom scheme

Your web server should serve:

• AASA and assetlinks files
• Smart app banner meta tags optional on iOS Safari
• Consistent URL structure between web routes and in-app routes

Backend teams own path conventions. If web uses /promo/123 but Flutter expects /promotions?id=123, campaigns will fail despite valid platform files. Align backend and API integration for web products with mobile routing early.

Testing on Real Devices

Simulator-only testing misses:

• Email client in-app browsers (Gmail, Outlook)
• SMS link handling
• Chrome Custom Tabs vs default browser on Android
• iOS pasteboard and long-press "Open in App" behavior

Test matrix (minimum):

Log parsed URI and final route in debug builds during QA week. Before physical QA, run Validate deep links (DevTools) to catch manifest, AASA, and assetlinks misconfigurations early.

When it breaks (and what you'll see)

These bugs often look like Flutter routing problems but are usually config issues on the website or native side.

AASA served with redirect

Symptom: link always opens Safari instead of your app.

CDN or www redirect breaks iOS verification. AASA URL must return 200 directly. Apple caches AASA via its CDN (Supporting associated domains), so fixes may not propagate to devices immediately after deploy.

Wrong Team ID or bundle ID in AASA

Symptom: iOS works in local dev builds but never in TestFlight or App Store builds.

Links open Safari instead of app with no obvious error.

Debug keystore fingerprint in assetlinks.json only

Symptom: works when you run from Android Studio, fails after installing from Play Store.

Works on dev builds, fails on Play Store builds. See Troubleshoot App Links for uppercase SHA-256, redirect, and Play App Signing mismatches.

Query param stripping by email ESP

Symptom: link opens the app but lands on the wrong screen or home screen.

Use path params for critical IDs when possible; treat query as optional metadata.

Router navigates before auth

Symptom: user lands on login screen; promo or order screen never appears.

User lands on protected screen, bounced to login, loses deep link context.

Multiple listeners

Symptom: screen flashes or navigates twice.

Two plugins subscribing cause double navigation or race crashes. One ownership layer for incoming links.

Pre-Release Checklist

Work top to bottom: website files → native config → Flutter router → device tests.

• [ ] Domain hosts valid AASA and assetlinks.json without redirects
• [ ] All marketing hosts (www, apex) covered in entitlements and intent filters
• [ ] Release signing fingerprints in assetlinks.json (Play App Signing aware)
• [ ] Flutter router maps every campaign path to a screen
• [ ] Auth-gated routes queue and resume deep links
• [ ] Web fallback pages exist for app-not-installed case
• [ ] Tested cold/warm start on physical iOS and Android
• [ ] Tested from email and SMS, not only pasted URLs
• [ ] Analytics events on deep link open and conversion funnel
• [ ] Runbook for marketing: approved URL format doc shared with growth team

Key Takeaways

• A deep link is a URL that opens a specific screen, not just your app icon.
• Use verified HTTPS links (Universal Links / App Links) for real campaigns, not custom schemes alone.
• Your website, native config, and Flutter router must all agree on the same paths.
• AASA (iOS) and assetlinks.json (Android) must be served correctly on every campaign host, with no redirects.
• Test on real devices from email and SMS, not only simulators; cold start is where most first-time bugs show up.

Which broke last on your project: iOS verification, Android autoVerify, or Flutter routing after cold start?

If deep links are in scope for your next release, scoping a mobile product with deep link requirements early keeps platform files, router design, and campaign URLs on the same checklist before store submission.