DEV Community

Cover image for Flutter Deep Linking: Complete Guide for Android App Links & iOS Universal Links
Ankush Lokhande
Ankush Lokhande

Posted on

Flutter Deep Linking: Complete Guide for Android App Links & iOS Universal Links

#deeplink #android #ios #mobile

👋 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
      ]
    }
  }
]
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode
  • Play Console SHA256: Navigate to: 
Protected with Play → Play Store protection → Protect app signing key → App signing
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Example:

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

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

Example:

https://yourdomain.com/product/12
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

Example:

https://yourdomain.com/anything
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Add the Associated Domains capability and include:

applinks:yourdomain.com
Enter fullscreen mode Exit fullscreen mode

For subdomains:

applinks:*.yourdomain.com
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

# 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;
  }
}
Enter fullscreen mode Exit fullscreen mode

Initialize Before runApp() 

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

  await DeepLinkService.init();

  runApp(const MyApp());
}
Enter fullscreen mode Exit fullscreen mode

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));
  }
}
Enter fullscreen mode Exit fullscreen mode

Listen for Incoming Links 

void initDeepLinkListener() {
  DeepLinkService.startListening((Uri uri) {
    handleDeepLink(uri);
  });
}
Enter fullscreen mode Exit fullscreen mode

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());
}
Enter fullscreen mode Exit fullscreen mode

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
}
Enter fullscreen mode Exit fullscreen mode
  • Case 2: Handle Multiple Dynamic URLs Examples: 
https://yourdomain.com/product/12
https://yourdomain.com/profile/45
https://yourdomain.com/booking/88
Enter fullscreen mode Exit fullscreen mode

Manage like this:

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

  case 'profile':
    break;

  case 'booking':
    break;
}
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

iOS

xcrun simctl openurl booted "https://yourdomain.com/product/12"
Enter fullscreen mode Exit fullscreen mode

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!👨‍💻

Top comments (0)