.NET MAUI Deep Linking

Use this skill when adding deep link or app link support to a .NET MAUI application.

Android App Links

IntentFilter on MainActivity

[IntentFilter( new[] { Android.Content.Intent.ActionView }, Categories = new[] { Android.Content.Intent.CategoryDefault, Android.Content.Intent.CategoryBrowsable }, DataScheme = "https", DataHost = "example.com", DataPathPrefix = "/products", AutoVerify = true)] public class MainActivity : MauiAppCompatActivity { }

• AutoVerify = true triggers Android domain verification at install time.

• Stack multiple IntentFilter attributes for different paths.

Digital Asset Links (domain verification)

Host /.well-known/assetlinks.json on your domain over HTTPS:

[{ "relation": ["delegate_permission/common.handle_all_urls"], "target": { "namespace": "android_app", "package_name": "com.example.myapp", "sha256_cert_fingerprints": ["AA:BB:CC:..."] } }]

Get SHA-256: keytool -list -v -keystore my-release-key.keystore -alias alias_name

Handle incoming intents

protected override void OnCreate(Bundle? savedInstanceState) { base.OnCreate(savedInstanceState); HandleDeepLink(Intent); }

protected override void OnNewIntent(Intent? intent) { base.OnNewIntent(intent); HandleDeepLink(intent); }

void HandleDeepLink(Intent? intent) { if (intent?.Action != Intent.ActionView || intent.Data is null) return; Shell.Current.GoToAsync(MapToRoute(intent.Data.ToString()!)); }

Test

adb shell am start -W -a android.intent.action.VIEW
-d "https://example.com/products/42" com.example.myapp adb shell pm get-app-links com.example.myapp

iOS Universal Links

Associated Domains entitlement

In Entitlements.plist :

<key>com.apple.developer.associated-domains</key> <array> <string>applinks:example.com</string> </array>

Apple App Site Association file

Host at /.well-known/apple-app-site-association (Content-Type: application/json ):

{ "applinks": { "details": [{ "appIDs": ["TEAMID.com.example.myapp"], "components": [{ "/": "/products/*" }] }] } }

iOS 14+ fetches AASA via Apple's CDN; changes may take 24 hours to propagate.

Handle Universal Links in MAUI

builder.ConfigureLifecycleEvents(events => { #if IOS || MACCATALYST events.AddiOS(ios => { ios.FinishedLaunching((app, options) => { var activity = options?[UIKit.UIApplication.LaunchOptionsUniversalLinkKey] as Foundation.NSUserActivity; HandleUniversalLink(activity?.WebPageUrl?.ToString()); return true; }); ios.ContinueUserActivity((app, activity, handler) => { if (activity.ActivityType == Foundation.NSUserActivityType.BrowsingWeb) HandleUniversalLink(activity.WebPageUrl?.ToString()); return true; }); ios.SceneWillConnect((scene, session, options) => { var activity = options.UserActivities? .ToArray<Foundation.NSUserActivity>() .FirstOrDefault(a => a.ActivityType == Foundation.NSUserActivityType.BrowsingWeb); HandleUniversalLink(activity?.WebPageUrl?.ToString()); }); }); #endif });

static void HandleUniversalLink(string? url) { if (string.IsNullOrEmpty(url)) return; MainThread.BeginInvokeOnMainThread(async () => await Shell.Current.GoToAsync(MapToRoute(url))); }

Testing

• Must test on a physical device. Simulator does not support Universal Links.

• Verify AASA: swcutil dl -d example.com on macOS.

Shell Navigation Integration

// Register in AppShell constructor Routing.RegisterRoute("products/detail", typeof(ProductDetailPage));

static string MapToRoute(string uri) { var segments = new Uri(uri).AbsolutePath.Trim('/').Split('/'); return segments switch { ["products", var id] => $"products/detail?id={id}", ["settings"] => "settings", _ => "//" }; }

Checklist

• Android: IntentFilter with AutoVerify = true on MainActivity

• Android: assetlinks.json at /.well-known/ with correct SHA-256

• Android: Handle intent in both OnCreate and OnNewIntent

• iOS: applinks: in Associated Domains entitlement

• iOS: AASA file at /.well-known/apple-app-site-association

• iOS: Handle via FinishedLaunching , ContinueUserActivity , SceneWillConnect

• iOS: Test on physical device (not simulator)

• Shell routes registered and URI-to-route mapping implemented