Index of every page on this site: llms.txt
All skills
davidortinau avatar

/maui-deep-linking

@79bb4bf
Run it yourself

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).

Use this Skill: https://skilld.dev/gh/davidortinau/maui-skills/maui-deep-linking

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈175 tokens for metadata: the name and description. ≈1k when used: this file. ≈953 more on demand in 1 file.

Description uses 8.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈701 characters, or 8.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

.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.
// ❌ 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);
}
  • SHA-256 fingerprint must match the signing key used for the build you're testing. Debug and release builds use different keys — update assetlinks.json accordingly or verification silently fails.
  • Test verification status with:
    adb shell pm get-app-links com.example.myapp
    Look for verified status, not just ask.

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.

// ❌ 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)));
}

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

  • Android: IntentFilter has AutoVerify = true on MainActivity
  • Android: assetlinks.json at /.well-known/ with correct SHA-256 for current signing key
  • Android: Intent handled in both OnCreate and OnNewIntent
  • Android: Verified with adb shell pm get-app-links
  • iOS: applinks:example.com in Associated Domains entitlement (not just example.com)
  • iOS: AASA file at /.well-known/apple-app-site-association with correct Team ID
  • iOS: All three lifecycle entry points handled
  • iOS: Tested on physical device (not simulator)
  • Shell routes registered before deep link callbacks fire
  • Navigation dispatched to main thread

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo4 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The skill provides implementation details for .NET MAUI deep linking. It includes an entry point for untrusted data via external URLs and provides instructions for executing command-line testing tools.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer8mo

    1/1 file flagged

Signed by skilld at 79bb4bf. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 8 months ago

README badge

README badge for davidortinau/maui-skills/maui-deep-linking