VOOZH about

URL: https://dev.to/ankushppie/flutter-deep-linking-complete-guide-for-android-app-links-ios-universal-links-4kde

⇱ Flutter Deep Linking: Complete Guide for Android App Links & iOS Universal Links - DEV Community

👋 Hey all,
Welcome back to the mobile development blog!

Ever tapped a link in WhatsApp or an email and landed directly on a specific screen inside an app? That’s deep linking in action.

For Flutter developers, deep linking sounds simple — open a URL and navigate to a screen. But in reality, it involves Android App Links, iOS Universal Links, server-side verification files, app configuration, and platform-specific setup, where even a small mistake can break the entire flow.

In this guide, we’ll implement deep linking in Flutter for both Android and iOS, including:

  • Android App Links setup
  • iOS Universal Links setup
  • Domain verification
  • Flutter route handling
  • Deep link testing
  • Common issues and fixes

using real-world examples and production-ready implementation.

👁 Let's Begin

Table Of Contents

# Flutter Deep Linking Implementation

In this section, we’ll configure deep linking for both Android and iOS so that URLs can open specific screens directly in the Flutter app.

This setup includes:

  • Adding deep linking support in Flutter
  • Configuring Android App Links
  • Configuring iOS Universal Links
  • Verifying domain ownership
  • Handling incoming URLs inside the app

By the end, your app will be able to open directly from supported web links and navigate users to the correct screen automatically.

# Step 1: Add Required Package

To handle incoming deep links inside the Flutter application, we’ll use the app_links package.
Install the latest version using:

flutter pub add app_links

This command automatically adds the latest compatible version to your pubspec.yaml file.

# Step 2: Domain Verification Setup

To allow your app to open links directly from your domain, both Android and iOS require domain verification files hosted on your server.

A). Android App Links Verification

Android uses an assetlinks.json file to verify that your domain belongs to your application.
Create this file:

https://yourdomain.com/.well-known/assetlinks.json

Example:

[
 {
 "relation": [
 "delegate_permission/common.handle_all_urls",
 "delegate_permission/common.get_login_creds"
 ],
 "target": {
 "namespace": "android_app",
 "package_name": "com.example.app",
 "sha256_cert_fingerprints": [
 "DEBUG_SHA256",
 "RELEASE_SHA256",
 "PLAY_CONSOLE_SHA256"
 ]
 }
 }
]

handle_all_urls → Opens app directly from supported links.
get_login_creds → Recommended for Play Store builds and Google credential sharing support.

SHA256 Fingerprints

You should add all possible SHA256 fingerprints:

  • Debug & Release SHA256: Run the following command to get both Debug and Release SHA256 fingerprints: 
cd android && ./gradlew signingReport
  • Play Console SHA256: Navigate to: 
Protected with Play → Play Store protection → Protect app signing key → App signing

Copy the: App signing certificate SHA-256 fingerprint

This is extremely important because production apps downloaded from Play Store are signed by Google Play, not your local keystore.

B). iOS Universal Links Verification

iOS uses an apple-app-site-association file for verification.

Create this file:

https://yourdomain.com/.well-known/apple-app-site-association

Example:

{
 "applinks": {
 "details": [
 {
 "appIDs": [
 "TEAM_ID.com.example.app"
 ],
 "components": [
 {
 "/": "*"
 }
 ]
 }
 ]
 }
}

Handle All URLs:
"/": "*" → Opens all supported URLs inside the app.
Handle Specific URLs Only:
"/product/*" → Opens only matching URLs inside the app.

Replace

  • TEAM_ID → Apple Developer Team ID
  • com.example.app → iOS Bundle Identifier

Verify Domain Association
Once the verification files are hosted, you can verify them using the following methods.

Android Verification:

https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://yourdomain.com&relation=delegate_permission/common.handle_all_urls

If everything is configured correctly, you should see your app’s package name in the response.

iOS Verification:

https://yourdomain.com/.well-known/apple-app-site-association

The browser should directly return the JSON response without downloading the file or showing HTML.

# Step 3: Configure Deep Linking

Now configure deep linking for both Android and iOS applications.

A). Android Deep Linking Configuration

Android allows you to configure deep linking in two ways:

  • Open only specific URLs
  • Open all links from your domain

Open your AndroidManifest.xml file:

android/app/src/main/AndroidManifest.xml

Inside your MainActivity, add one of the following intent-filter configurations.

Option 1: Handle Specific URLs Only
Use this when you want to open only selected paths inside the app.

<intent-filter android:autoVerify="true">
 <action android:name="android.intent.action.VIEW" />

 <category android:name="android.intent.category.DEFAULT" />
 <category android:name="android.intent.category.BROWSABLE" />

 <data
 android:scheme="https"
 android:host="yourdomain.com"
 android:pathPrefix="/product" />
</intent-filter>

Example:

https://yourdomain.com/product/12

Only URLs starting with /product will open the app.

Option 2: Handle All Links from Domain
Use this when all URLs from your domain should open inside the app.

<intent-filter android:autoVerify="true">
 <action android:name="android.intent.action.VIEW" />

 <category android:name="android.intent.category.DEFAULT" />
 <category android:name="android.intent.category.BROWSABLE" />

 <data
 android:scheme="https"
 android:host="yourdomain.com" />
</intent-filter>

Example:

https://yourdomain.com/anything

Any valid URL from the domain can open the application.

B). iOS Universal Links Configuration

Now let’s configure Universal Links for iOS so supported URLs can directly open your Flutter application instead of opening in Safari.

Associated Domains Setup

Open your iOS project in Xcode & navigate to:

Runner → Signing & Capabilities

Add the Associated Domains capability and include:

applinks:yourdomain.com

For subdomains:

applinks:*.yourdomain.com

Add Associated Domains in Info.plist

<key>com.apple.developer.associated-domains</key>
<array>
 <string>applinks:yourdomain.com</string>
</array>
<key>LSApplicationQueriesSchemes</key>
<array>
 <string>https</string>
</array>

# Step 4: Handle Deep Link Redirection in Flutter

Now that platform configuration is complete, let’s handle incoming deep links inside the Flutter application.

This implementation supports:

  • Cold start links (app killed state)
  • Foreground links
  • Background links
  • Specific route handling
  • Dynamic route parsing for multiple URLs

Create deep_link_service.dart

Create a reusable deep link service:

import 'dart:async';
import 'package:app_links/app_links.dart';
import 'package:flutter/foundation.dart';

class DeepLinkService {
 static final AppLinks _appLinks = AppLinks();
 static StreamSubscription? _subscription;

 static String? pendingRoute;

 /// Call before runApp()
 static Future<void> init() async {
 try {
 final Uri? initialUri = await _appLinks.getInitialLink();

 if (initialUri != null) {
 if (kDebugMode) {
 print('DeepLink cold start: $initialUri');
 }

 pendingRoute = initialUri.toString();
 }
 } catch (e) {
 if (kDebugMode) {
 print('DeepLink init error: $e');
 }
 }
 }

 /// Listen for foreground/background links
 static void startListening(Function(Uri uri) onLinkReceived) {
 _subscription?.cancel();

 _subscription = _appLinks.uriLinkStream.listen(
 (Uri uri) {
 if (kDebugMode) {
 print('DeepLink foreground: $uri');
 }

 onLinkReceived(uri);
 },
 onError: (e) {
 if (kDebugMode) {
 print('DeepLink stream error: $e');
 }
 },
 );
 }

 static void dispose() {
 _subscription?.cancel();
 _subscription = null;
 }
}

Initialize Before runApp() 

void main() async {
 WidgetsFlutterBinding.ensureInitialized();

 await DeepLinkService.init();

 runApp(const MyApp());
}

Start Listening Inside Controller 

@override
void onInit() {
 super.onInit();

 initDeepLinkListener();

 /// Handle cold start deep link
 final String? pendingRoute = DeepLinkService.pendingRoute;

 DeepLinkService.pendingRoute = null;

 if (pendingRoute != null) {
 handleDeepLink(Uri.parse(pendingRoute));
 }
}

Listen for Incoming Links 

void initDeepLinkListener() {
 DeepLinkService.startListening((Uri uri) {
 handleDeepLink(uri);
 });
}

Handle Route Redirection

This is the main navigation handler where you can support:

  • Single URL pattern
  • Multiple URLs
  • Dynamic IDs
  • Full app routing 
void handleDeepLink(Uri uri) {
 final segments = uri.pathSegments;

 /// Example:
 /// https://yourdomain.com/product/12
 if (segments.length >= 2 && segments[0] == 'product') {
 final productId = segments[1];

 Get.to(
 () => ProductDetailsScreen(
 productId: productId,
 ),
 );

 return;
 }

 /// Example:
 /// https://yourdomain.com/profile/45
 if (segments.length >= 2 && segments[0] == 'profile') {
 final userId = segments[1];

 Get.to(
 () => ProfileScreen(
 userId: userId,
 ),
 );

 return;
 }

 /// Default fallback
 Get.to(() => const HomeScreen());
}

Handle Single Link vs All Links

  • Case 1: Handle Only One Specific URL Example: 
https://yourdomain.com/product/12
if (segments[0] == 'product') {
 // Navigate to product screen
}
  • Case 2: Handle Multiple Dynamic URLs Examples: 
https://yourdomain.com/product/12
https://yourdomain.com/profile/45
https://yourdomain.com/booking/88

Manage like this:

switch (segments[0]) {
 case 'product':
 break;

 case 'profile':
 break;

 case 'booking':
 break;
}

This approach makes the deep linking flow scalable and easy to maintain for large Flutter applications.

# Step 5: Testing Deep Links

This is very important because most developers struggle during testing.

Include:

  • Android testing command
  • iOS testing command
  • Real device testing
  • Browser / WhatsApp / Email testing

Android

adb shell am start \
-a android.intent.action.VIEW \
-d "https://yourdomain.com/product/12"

iOS

xcrun simctl openurl booted "https://yourdomain.com/product/12"

Let's Wrap!

Deep linking is an essential feature for modern mobile applications. It allows users to open specific screens directly from URLs, creating a faster and smoother user experience.

Although the setup involves platform-specific configuration for Android and iOS, once everything is configured correctly, deep linking becomes a powerful and scalable navigation system for your Flutter application.

With Android App Links, iOS Universal Links, proper domain verification, and Flutter route handling, your app is now ready to support production-ready deep linking across both platforms.

👁 Thanks for reading

If you found this blog helpful or have any further questions, we would love to hear from you. Feel free to reach out and follow us on our social media platforms for more tips and tutorials on tech-oriented posts.

Happy coding!👨‍💻