DEV Community: Jasper

Flutter Deep Links for Beginners: A Production Setup Checklist

Jasper — Wed, 10 Jun 2026 01:37:37 +0000

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:

Your website (verification files that prove you own the domain)
iOS or Android native config (entitlements, manifest entries)
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:

User taps https://example.com/promo/123 in email, SMS, or a browser.
Phone checks whether your app is allowed to handle that domain (verification files on your server + native app config).
OS opens the app (if installed and verified) and passes the full URL to Flutter.
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

Term	Plain meaning
Deep link	URL that opens a specific in-app screen
Universal Link (iOS)	HTTPS deep link verified by Apple
App Link (Android)	Same idea on Android
AASA	Apple's domain verification file (`apple-app-site-association`) on your website
assetlinks.json	Android's domain verification file on your website
Custom URL scheme	`myapp://` shortcut; easy to demo locally, weak for email campaigns
Intent filter	Android manifest entry that says "this app handles these URLs"

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.

Mechanism	Example	Pros	Cons
Custom URL scheme	`myapp://promo/123`	Fast to prototype	Not verified; conflicts with other apps; email clients may block
iOS Universal Links	`https://example.com/promo/123`	Verified domain; opens app if installed	Requires apple-app-site-association (AASA) file
Android App Links	`https://example.com/promo/123`	Verified domain; avoids disambiguation dialog	Requires assetlinks.json

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:

Listen for initial link on cold start (getInitialLink)
Subscribe to stream for warm start (uriLinkStream)
Parse path and query params
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:

App installed: open app to target screen (Universal / App Link)
App not installed: show mobile web equivalent or store landing page
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):

Source	iOS physical	Android physical
Notes app pasted URL	✓	✓
Email tap	✓	✓
SMS tap	✓	✓
Mobile Safari / Chrome address bar	✓	✓
Cold start (app killed)	✓	✓
Warm start (background)	✓	✓

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.

State Management in Production Flutter Apps: What Actually Held Up at Scale

Jasper — Thu, 28 May 2026 00:07:57 +0000

State management rarely feels urgent on week one of a Flutter project.

Screens come together fast. setState works. Provider or Riverpod gets wired up in an afternoon. Demos look great in the simulator.

Then month four or five hits. A second developer joins. You add offline-friendly flows, push notifications, and deeper API integration. Navigation stacks get taller. The same bug shows up on two different screens. Suddenly the state choices you made early are everywhere, and changing them feels expensive.

I've been shipping Flutter apps on cross-platform mobile work for clients who need store-ready iOS and Android builds, not just a polished prototype. These are the patterns that held up in production, and the ones that did not.

This is not a framework ranking. It is what we saw once real users, real releases, and real teammates entered the picture.

Why State Management Decisions Show Up Late in Flutter Projects

Flutter makes it easy to defer architectural decisions. Widgets compose quickly. Hot reload hides how tangled things are becoming. Async work, platform channels, and auth flows often land after the first sprint demo.

By the time pain shows up, state is spread across parent widgets, inherited notifiers, and ad-hoc service singletons. Refactoring feels risky because nobody is sure which screen owns which piece of data.

The symptoms we noticed first

These showed up before anyone said "we picked the wrong library":

Screens that were fast to build but painful to change
Duplicate API calls after navigation pop/push cycles
Bug fixes that resurfaced in a different widget tree branch
QA reports that only reproduced on one platform build

None of that is unique to Flutter. It is what happens when UI state, domain state, and API-driven data get mixed without clear boundaries.

What "production scale" actually meant for us

For our client apps, production scale was not millions of users on day one. It usually meant:

More features shipping after the first store release
More developers touching the same modules
More edge cases around slow networks, stale tokens, and partial offline behavior
Post-MVP iteration on a codebase that still had to pass App Store and Google Play review

That is when state management stops being a tutorial topic and starts being a delivery constraint.

Five Lessons From Real Flutter Client Apps

These lessons came from shipping and maintaining Flutter projects, not from comparing packages in isolation. Your stack may differ. The trade-offs probably will not.

1. setState and local state are fine until they are not

Local state still makes sense for isolated UI: toggles, form field focus, animation controllers, short-lived modal flows. We still use it in those cases.

It became a problem when business logic crept into StatefulWidget classes. Fetching data, handling errors, and coordinating navigation from one screen's setState block made that screen the hidden owner of behavior other features needed later.

We also paid for it in testing. Widgets that mixed layout, side effects, and API calls were harder to exercise on both iOS and Android CI builds. Splitting view logic from data flow, even in small steps, made regressions easier to catch.

Rule of thumb we use now: if another screen might need this data within two sprints, local setState is probably too local.

2. Provider got us moving; Riverpod and Bloc earned their keep later

Early in MVP delivery, Provider was often enough. The team could move quickly, dependencies were familiar, and the learning curve stayed low. That matters when you are trying to reach a first release on a fixed timeline.

As features accumulated, we leaned more on Riverpod or Bloc in modules where async boundaries and testability mattered most. Riverpod's explicit providers and overrides helped us reason about dependencies in larger apps. Bloc's event/state separation made complex flows (auth refresh, paginated lists, multi-step forms) easier to trace in code review.

We did not migrate everything at once. Mixed patterns are fine if they are intentional: one primary approach per feature folder, documented in a short README or ADR note.

A pattern we reuse for list screens looks like this (Riverpod example):

final ordersProvider = FutureProvider.autoDispose<List<Order>>((ref) async {
  final repo = ref.watch(orderRepositoryProvider);
  return repo.fetchOrders();
});

The point is not the syntax. It is that loading, success, and failure have a predictable home instead of living inside a widget's initState.

See the Riverpod documentation and Bloc library docs when you want deeper references. We treat them as tools, not identity.

3. Global state is rarely the whole answer

It is tempting to put "the app state" in one global store and call it done. That worked until features had different lifecycles, permissions, and refresh rules.

What helped us more was scoping state by feature and separating layers:

UI state: expanded panels, selected tabs, scroll position
Domain state: cart contents, draft form values, in-progress job status
Remote data: API responses cached with clear invalidation rules

A repository layer became the stable seam for backend integration. Widgets and notifiers depended on repositories, not raw HTTP clients scattered through the tree. When an endpoint changed, we fixed one place instead of five screens.

Global singletons still exist in our apps (session, environment config, analytics). They are just not where feature logic lives.

4. Error, loading, and empty states need a first-class plan

Happy-path-only UI is the fastest way to ship a demo and the slowest way to stabilize a production app.

We lost time to bugs that were really missing state models:

Infinite spinners when an API returned an empty list
Stale data shown after a failed refresh
Retry buttons that fired duplicate requests
Error messages that disappeared on navigation and never came back

Once we modeled async work as explicit phases (loading, success, empty, error), tests got useful and support tickets dropped. AsyncValue in Riverpod and sealed state classes in Bloc both push you in that direction. Even with Provider, a small wrapper type for Resource<T> or similar beats treating null as "still loading."

Offline-adjacent behavior does not require a full offline-first architecture on day one. It does require deciding what the UI should show when the network is slow or unavailable, before users report it in reviews.

5. Tests and onboarding broke our early "clever" patterns

Clever abstractions age badly when only one person understands them.

We had listeners buried in widget trees, magic context.read calls after async gaps, and "temporary" global notifiers that never left. Refactors broke silently. New developers copied the wrong pattern because it was the fastest path to green builds.

What helped onboarding:

Predictable folder layout (features/orders/data, features/orders/presentation)
One documented state approach per feature
Widget tests for UI edge cases, integration tests for critical flows (login, checkout, submit)

Integration tests cost more to maintain, but they paid off on auth and payment paths where widget tests alone missed navigation regressions. The Flutter integration testing docs are worth reading before you promise coverage you cannot sustain.

What We Would Do Differently on the Next Flutter App

If we could replay the first six weeks of a typical client project, we would spend more time on boundaries and less time debating which package "wins" on Reddit.

State management is a team contract. The library is just how you enforce it.

Pre-launch checklist we use now

Before we call architecture "good enough" for a store release, we walk through this:

Scope state by feature, not by screen count alone
Define async contracts early: loading, error, empty, success (and when to retry)
Pick one primary pattern per layer and stick to it unless there is a written reason to diverge
Document where state lives before the team doubles in size
Plan for post-MVP growth before the first App Store or Play Store submission

None of that blocks an MVP. It prevents the MVP from becoming a rewrite trigger at month six.

Closing

Working on production Flutter apps changed how we think about state. Tutorials optimize for clarity in isolation. Client work optimizes for change over time: new endpoints, new teammates, new store builds, new platform quirks.

We are still learning. Riverpod, Bloc, and Provider will keep evolving. The constant is paying attention to boundaries, async behavior, and what the next developer will assume when they open the repo.

What broke first in your Flutter apps once you moved past the demo stage? Curious which lesson maps to your experience.

If you are planning a Flutter MVP, scoping a mobile MVP early (state boundaries, async contracts, store readiness) saves pain later.

Flutter 3.44 Highlights From Google I/O 2026: What's New and What Matters

Jasper — Thu, 21 May 2026 02:54:10 +0000

I tuned into the What's new in Flutter session at Google I/O 2026 expecting a standard release walkthrough. Flutter 3.44 felt bigger than that. The team framed it around scaling to more users on more devices, and the demos backed it up: agentic hot reload, generative UI, Hybrid Composition++ on Android, Swift Package Manager as the iOS and macOS default, and Flutter running in a 2026 Toyota RAV4 infotainment system.

If you're wondering what actually matters in this release, the short answer is that 3.44 pushes Flutter further into AI-assisted development, embedded deployments, and platform-native integration, without treating those as side experiments. Most of what landed here is production-oriented.

I've been following Flutter releases with our team at Spice Factory Philippines, and this one stood out because it connects everyday app work to where the ecosystem is clearly heading.

Ecosystem Growth by the Numbers at Google I/O 2026

The session opened with a simple idea: Flutter is everywhere, everyday, built by everyone, for everyone.

On stage, they backed that up with numbers that are hard to ignore. The pub.dev ecosystem hit over 1.3 billion package downloads in the last 30 days alone. Flutter is now the second most popular mobile SDK on both major app stores, with 1.5 million monthly developers, up 50% in a year. This release cycle alone landed 972 commits from 178 contributors, including 61 first-time contributors.

That context matters. 3.44 is not a collection of niche experiments. It reads like a release built for teams shipping real products across mobile, desktop, web, and embedded hardware.

AI and Developer Experience: Agentic Hot Reload, GenUI, and DevTools

This was the part of the session that felt most immediately useful for day-to-day work.

Agentic Hot Reload is the headline feature here. Through the Dart and Flutter MCP server, coding agents can now automatically find and connect to your running app, then hot reload after UI changes. Prompt your agent to tweak a screen, and you see the result without manual setup. They also hardened dependency search for agents and consolidated MCP tool definitions to cut token costs.

Alongside that, Dart and Flutter Agent Skills give agents step-by-step, task-oriented guidance for things like integration tests and localization setup. If you already use Cursor or similar tools, this is worth trying on your next Flutter task.

On the product side, GenUI (built on the open A2UI protocol) stood out in the demos. Instead of AI responses as walls of markdown, agents compose real Flutter UI on the fly. The Hatcha event-planning demo and apps like Finnish it show what that looks like in practice. Li-Te Cheng from Google DeepMind also shared practical takeaways from the Gemini App's Visual Layout experiment: lean on opinionated frameworks for consistency, use an "AI critic" loop for reliability, and balance speed with templates when you need control.

Behind the scenes, DevTools got snappier (WASM by default), and Widget Previews reduce IDE memory usage by up to 50% by leaning on the Dart Analysis Server. Small wins, but the kind that make long sessions less painful.

Platform Updates for Android, iOS, Desktop, and Embedded

Android: Hybrid Composition++ and AGP 9 Kotlin Changes

Hybrid Composition++ (HCPP) solves a long-standing Platform Views tradeoff: frame rate vs fidelity. It delegates compositing to the Android OS using Vulkan and SurfaceControl, which means smoother scrolling, better touch input, and reliable SurfaceView support. It is opt-in for now via --enable-hcpp or a manifest flag:

<meta-data
  android:name="io.flutter.embedding.android.EnableHcpp"
  android:value="true" />

Flutter also reads display corner radii from Android hardware through MediaQuery, which helps on aggressively rounded screens.

One heads-up for Android teams: AGP 9 built-in Kotlin means manually applying the Kotlin Gradle plugin can break builds. If you maintain plugins, the migration guide requires a minimum Flutter constraint of 3.44.

iOS and macOS: Swift Package Manager by Default

Swift Package Manager is now the default for iOS and macOS. The CLI migrates your Xcode project automatically. Plugins still on CocoaPods trigger a fallback with a warning, so check your dependency tree. Apple is also moving toward requiring UIScene lifecycle support, so migrate before enforcement catches you off guard.

Desktop and Embedded: Canonical, Toyota RAV4, and LG webOS

Canonical is now the lead maintainer for Flutter Desktop (Linux, Windows, macOS). Experimental multi-window APIs are progressing on the main channel: tooltips, popup windows on macOS, and separate dialog windows.

The embedded demos got the crowd reaction. Flutter powers the 2026 Toyota RAV4 multimedia system, and LG's webOS SDK (with hot reload, Riverpod, Firebase plugins, and more) is coming soon for big-screen targets.

Material and Cupertino Decoupling From the Core Framework

Material and Cupertino libraries are frozen in the core framework as of 3.44. They will move to standalone packages (material_ui and cupertino_ui) with independent versioning in a future release.

Practically, that means design system updates can ship on their own cadence instead of waiting for the next Flutter SDK. If you are planning a Material 3 migration or heavy Cupertino customization, keep an eye on the decoupling tracking issue and start thinking about package-based imports early.

How to Upgrade to Flutter 3.44: Migration Checklist

If you want to try the highlights without reading every release note:

Run flutter upgrade
Test HCPP if your app embeds native Android views (maps, web views, etc.)
Audit your Android Gradle/Kotlin setup for AGP 9 compatibility
Check iOS plugins for SwiftPM support
Experiment with Agentic Hot Reload if you use an AI coding agent

For the full breakdown, see the official Flutter 3.44 release post and the Dart 3.12 release notes.

Key Takeaways From the What's New in Flutter Session

The session made one thing clear: Flutter is not just iterating on widgets anymore. It is positioning for agentic development workflows, generative UI, and deployments from car dashboards to smart TVs.

For our team, Agentic Hot Reload and the Android HCPP improvements are the first things worth testing on active projects. The Material/Cupertino decoupling is the longer-term architectural shift to watch.

Which 3.44 change are you trying first? Curious what stands out for other teams shipping Flutter in production.

If you want to see how we approach multi-platform app development for real client work, you can check what we do here: https://spice-factory.ph/