| name | maui-deep-linking |
| description | Guide for implementing deep linking in .NET MAUI apps. Covers Android App Links with intent filters, Digital Asset Links, and AutoVerify; iOS Universal Links with Associated Domains entitlements and Apple App Site Association files; custom URI schemes; and domain verification for both platforms. USE FOR: "deep linking", "app links", "universal links", "custom URI scheme", "intent filter", "Associated Domains", "Digital Asset Links", "open app from URL", "handle incoming URL", "domain verification". DO NOT USE FOR: in-app Shell navigation (use maui-shell-navigation), push notification handling (use maui-push-notifications), or web content embedding (use maui-hybridwebview).
|
.NET MAUI Deep Linking
Platform Gotchas
Android
AutoVerify = true is required on the IntentFilter for App Links (not
just deep links). Without it, Android shows a disambiguation dialog instead
of opening your app directly.- Handle intent in both
OnCreate and OnNewIntent.
OnCreate fires for cold starts; OnNewIntent fires when the app is already
running. Missing either means links silently fail in one scenario.
protected override void OnCreate(Bundle? savedInstanceState)
{
base.OnCreate(savedInstanceState);
HandleDeepLink(Intent);
}
protected override void OnCreate(Bundle? savedInstanceState)
{
base.OnCreate(savedInstanceState);
HandleDeepLink(Intent);
}
protected override void OnNewIntent(Intent? intent)
{
base.OnNewIntent(intent);
HandleDeepLink(intent);
}
iOS
- ⚠️ Universal Links do NOT work in the Simulator. You must test on a
physical device.
- AASA changes take up to 24 hours to propagate through Apple's CDN
(iOS 14+). During development, use the
?mode=developer query param or
Apple's CDN diagnostics: swcutil dl -d example.com.
- Handle all three entry points:
FinishedLaunching, ContinueUserActivity,
and SceneWillConnect. Missing any one causes links to fail for specific
app states (cold start, background resume, or scene-based launch).
applinks: prefix is required in the Associated Domains entitlement.
Writing just example.com instead of applinks:example.com silently fails.
Common Mistakes
Forgetting MainThread.BeginInvokeOnMainThread
Deep link callbacks can fire on background threads. Shell navigation must run
on the main thread.
static void HandleUniversalLink(string? url)
{
if (string.IsNullOrEmpty(url)) return;
Shell.Current.GoToAsync(MapToRoute(url));
}
static void HandleUniversalLink(string? url)
{
if (string.IsNullOrEmpty(url)) return;
MainThread.BeginInvokeOnMainThread(async () =>
await Shell.Current.GoToAsync(MapToRoute(url)));
}
Route not registered before navigation
Register Shell routes in AppShell constructor before any deep link can
fire. If the route doesn't exist, GoToAsync throws silently or navigates
to root.
Custom URI schemes vs. App Links / Universal Links
| Approach | Verified | Fallback to browser | Recommended |
|---|
Custom URI scheme (myapp://) | No | No | Only for app-to-app communication |
Android App Links (https://) | Yes | Yes | ✅ Production web links |
iOS Universal Links (https://) | Yes | Yes | ✅ Production web links |
⚠️ Custom URI schemes are not verified — any app can register the same
scheme. Use https:// App Links / Universal Links for user-facing URLs.
Debugging Checklist
