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).
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.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.// ❌ Only handles cold-start links
protected override void OnCreate(Bundle? savedInstanceState)
{
base.OnCreate(savedInstanceState);
HandleDeepLink(Intent);
}
// ✅ Handles both cold-start and warm-start links
protected override void OnCreate(Bundle? savedInstanceState)
{
base.OnCreate(savedInstanceState);
HandleDeepLink(Intent);
}
protected override void OnNewIntent(Intent? intent)
{
base.OnNewIntent(intent);
HandleDeepLink(intent);
}
assetlinks.json accordingly or verification silently fails.adb shell pm get-app-links com.example.myapp
verified status, not just ask.?mode=developer query param or
Apple's CDN diagnostics: swcutil dl -d example.com.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.MainThread.BeginInvokeOnMainThreadDeep link callbacks can fire on background threads. Shell navigation must run on the main thread.
// ❌ May crash — GoToAsync called off the main thread
static void HandleUniversalLink(string? url)
{
if (string.IsNullOrEmpty(url)) return;
Shell.Current.GoToAsync(MapToRoute(url));
}
// ✅ Dispatch to main thread
static void HandleUniversalLink(string? url)
{
if (string.IsNullOrEmpty(url)) return;
MainThread.BeginInvokeOnMainThread(async () =>
await Shell.Current.GoToAsync(MapToRoute(url)));
}
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.
| 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.
IntentFilter has AutoVerify = true on MainActivityassetlinks.json at /.well-known/ with correct SHA-256 for current signing keyOnCreate and OnNewIntentadb shell pm get-app-linksapplinks:example.com in Associated Domains entitlement (not just example.com)/.well-known/apple-app-site-association with correct Team ID