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

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

Table Of Contents

Flutter Deep Linking Implementation

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

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.

推荐订阅源

DEV Community

# Flutter Deep Linking Implementation

# Step 1: Add Required Package

# Step 2: Domain Verification Setup

A). Android App Links Verification

B). iOS Universal Links Verification

# Step 3: Configure Deep Linking

A). Android Deep Linking Configuration

B). iOS Universal Links Configuration

# Step 4: Handle Deep Link Redirection in Flutter

Create `deep_link_service.dart`

Initialize Before `runApp()`

Start Listening Inside Controller

Listen for Incoming Links

Handle Route Redirection

# Step 5: Testing Deep Links

Let's Wrap!

Happy coding!👨‍💻

推荐订阅源

DEV Community

# Flutter Deep Linking Implementation

# Step 1: Add Required Package

# Step 2: Domain Verification Setup

A). Android App Links Verification

B). iOS Universal Links Verification

# Step 3: Configure Deep Linking

A). Android Deep Linking Configuration

B). iOS Universal Links Configuration

# Step 4: Handle Deep Link Redirection in Flutter

Create deep_link_service.dart

Initialize Before runApp()

Start Listening Inside Controller

Listen for Incoming Links

Handle Route Redirection

# Step 5: Testing Deep Links

Let's Wrap!

Happy coding!👨‍💻

Create `deep_link_service.dart`

Initialize Before `runApp()`