deep-linking

Deep Linking - Universal Links & App Links

Deep linking setup for iOS (Universal Links) and Android (App Links) with GoRouter integration.

When to Use This Skill

• Adding deep link support to a Flutter app
• Configuring Universal Links for iOS
• Configuring App Links for Android
• Handling custom URL schemes
• Integrating deep links with GoRouter
• User asks "add deep linking", "universal links", "app links", or "URL handling"

Questions to Ask

1. Domain: What domain will host the deep links? (e.g., example.com)
2. Paths: Which paths should open the app? (e.g., /products/*, /users/*)
3. Custom scheme: Need a custom URL scheme fallback? (e.g., myapp://)
4. Environments: Multiple domains? (e.g., staging.example.com, example.com)
5. Backend access: Can you host .well-known files on the server?

Reference Files

• reference/router/deep_link_handler.dart - GoRouter deep link config
• templates/ios/Runner.entitlements - Associated Domains
• templates/android/android_manifest_deeplinks.xml - Intent filters

See: implementation-guide.md for complete setup.

Workflow

Phase 1: Domain Verification

1. Create apple-app-site-association file (see ios-guide.md)
2. Create assetlinks.json file (see android-guide.md)
3. Host files at https://domain.com/.well-known/
4. Verify HTTPS and correct MIME types

Phase 2: iOS Configuration

1. Add Associated Domains capability in Xcode
2. Add domain to Runner.entitlements
3. Handle links in AppDelegate (if needed)

Phase 3: Android Configuration

1. Add intent filters to AndroidManifest.xml
2. Set autoVerify="true" for App Links
3. Generate and add SHA-256 fingerprint to assetlinks.json

Phase 4: GoRouter Integration

1. Configure GoRouter with deep link paths
2. Add route parameter extraction
3. Handle unknown deep links gracefully
4. Test with adb and xcrun commands

Core API

// GoRouter handles deep links automatically
GoRouter(routes: [
  GoRoute(path: '/products/:id', builder: (context, state) =>
    ProductScreen(productId: state.pathParameters['id']!)),
]);
// Manual: GoRouter.of(context).go(Uri.parse(deepLink).path);