How to Implement App Links and Universal Links in Flutter: Complete Guide

Deep linking is an important feature in modern mobile applications. It allows users to open specific screens inside an application directly from a website, email, notification, QR code, or shared URL.

For example, imagine a user receives a product link through WhatsApp. Instead of opening the application’s home screen and manually searching for the product, tapping the link can take the user directly to that product’s detail page.

Flutter supports this functionality through Android App Links and iOS Universal Links.

Both technologies use standard HTTPS URLs to connect websites with mobile applications. However, Android and iOS require different configurations to verify that an application is authorized to handle links from a particular domain.

In this guide, you will learn how to implement Android App Links and iOS Universal Links in Flutter, configure domain verification, handle incoming URLs, navigate to specific screens using GoRouter, and troubleshoot common deep-linking problems.

We will also cover practical examples, security considerations, testing commands, and production best practices.

1. What Are Deep Links in Flutter?

A deep link is a URL that opens a specific location inside a mobile application instead of simply launching its home screen.

For example, consider an e-commerce application with the following product URL:

https://example.com/products/123

When a user opens this URL, the application can navigate directly to the product detail screen for product ID 123.

If the application is not installed, the same URL can open the corresponding product page on the website.

This creates a consistent navigation experience across websites and mobile applications.

Types of deep links

There are three commonly discussed approaches to deep linking.

Type	Description	Example
Custom URL scheme	Uses an application-specific URL scheme.	myapp://products/123
Android App Links	Uses verified HTTPS URLs associated with an Android application.	https://example.com/products/123
iOS Universal Links	Uses HTTPS URLs associated with an iOS application.	https://example.com/products/123

Custom URL schemes are relatively simple to configure, but they do not provide the same domain ownership verification as Android App Links and iOS Universal Links.

For applications that already have a website or public HTTPS domain, verified links are generally a more appropriate approach for opening shared web content inside the application.

2. Android App Links vs iOS Universal Links

Android App Links and iOS Universal Links serve similar purposes, but their configuration and verification mechanisms are different.

Android App Links use an Android intent filter and a Digital Asset Links file to establish a relationship between a website and an Android application.

iOS Universal Links use an Associated Domains entitlement and an Apple App Site Association file to establish a relationship between a website and an iOS application.

Feature	Android App Links	iOS Universal Links
Platform	Android	iOS
URL format	HTTPS	HTTPS
Domain verification file	assetlinks.json	apple-app-site-association
App configuration	AndroidManifest.xml	Associated Domains entitlement
Application identity	Package name and signing certificate	Apple Team ID and Bundle ID
Domain association	Digital Asset Links	Apple App Site Association
Flutter navigation	Flutter Router, GoRouter, or a compatible link handler	Flutter Router, GoRouter, or a compatible link handler

Both platforms require configuration outside Flutter itself.

Adding a route to your Flutter application is not sufficient to make verified links work.

The operating system must also recognize that your application is authorized to handle URLs belonging to the associated domain.

3. How App Links and Universal Links Work

Before implementing deep linking, it helps to understand how the operating system and Flutter application work together.

Consider this URL:

https://example.com/products/123

The linking process generally works as follows:

1. A user taps the HTTPS link.
2. The operating system checks whether an installed application is associated with the URL’s domain.
3. The operating system evaluates the applicable link-handling rules and user preferences.
4. If the application is selected to handle the link, it receives the URL.
5. Flutter processes the incoming route.
6. The application opens the corresponding product detail screen.

If the application does not handle the link, the URL can open in a web browser.

The exact behavior depends on the platform, verification status, link context, application installation state, and user preferences.

For example, iOS may keep a user in Safari when they tap a Universal Link pointing to the same domain they are already browsing.

A verified association does not guarantee that every tap will always open the native application.

4. Project Requirements

Before starting, make sure you have the following:

• A Flutter project configured for Android and iOS.
• An HTTPS domain that you control.
• Access to your website’s hosting configuration.
• Your Android application package name.
• Your Android signing certificate’s SHA-256 fingerprint.
• Your iOS Bundle ID and Apple Developer Team ID.
• A physical device or suitable test environment.

For this tutorial, we will use the following example configuration.

Configuration	Example value
Website domain	example.com
Product URL	https://example.com/products/123
Android package name	com.example.myapp
iOS Bundle ID	com.example.myapp
Apple Team ID	ABCDE12345

Replace these example values with your actual application and website details.

You must control the domain used for verification because both Android and iOS require you to publish association files on that domain.

5. Choose a Deep-Link Handling Approach in Flutter

Flutter supports deep linking through its navigation and routing system.

You can use Flutter’s built-in Router API, a routing package such as GoRouter, or a dedicated incoming-link package.

For applications that already use GoRouter, the routing system can handle incoming deep links without requiring an additional link-listening package.

For applications using GetX or custom navigation, a package such as app_links can provide a stream of incoming URLs that you can process manually.

Important: Avoid enabling multiple independent deep-link handlers for the same incoming URL unless you have deliberately designed how they interact.

For example, combining Flutter’s default deep-link handling with a separate plugin listener can cause duplicate navigation or conflicting route behavior.

In this guide, we will first implement deep linking using GoRouter.

Later, we will cover an alternative implementation using the app_links package.

6. Install GoRouter in Flutter

GoRouter is a declarative routing package for Flutter that supports URL-based navigation, nested routes, redirects, and deep linking.

Official package: https://pub.dev/packages/go_router

Install it using:

flutter pub add go_router

Next, create a routing file.

Example project structure:

lib/
│
├── main.dart
│
├── app/
│   └── app_router.dart
│
├── features/
│   ├── home/
│   │   └── screens/
│   │       └── home_screen.dart
│   │
│   └── products/
│       └── screens/
│           └── product_detail_screen.dart
│
└── core/
    └── services/

This structure separates routing logic from individual feature screens.

For larger applications, you can organize routes by feature and combine them in a central application router.

7. Configure Deep-Link Routes Using GoRouter

Create the following file:

lib/app/app_router.dart

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

import '../features/home/screens/home_screen.dart';
import '../features/products/screens/product_detail_screen.dart';

final GoRouter appRouter = GoRouter(
  initialLocation: '/',

  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) {
        return const HomeScreen();
      },
    ),

    GoRoute(
      path: '/products/:id',
      builder: (context, state) {
        final productId =
            state.pathParameters['id']!;

        return ProductDetailScreen(
          productId: productId,
        );
      },
    ),
  ],

  errorBuilder: (context, state) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Page Not Found'),
      ),
      body: const Center(
        child: Text(
          'The requested page could not be found.',
        ),
      ),
    );
  },
);

The route:

/products/:id

accepts a dynamic product ID.

For example:

https://example.com/products/123

corresponds to:

/products/123

GoRouter can extract the product ID and pass it to the product detail screen.

Configure MaterialApp.router

Open main.dart and configure the application to use GoRouter.

import 'package:flutter/material.dart';

import 'app/app_router.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp.router(
      debugShowCheckedModeBanner: false,

      title: 'Flutter Deep Linking',

      routerConfig: appRouter,
    );
  }
}

Using MaterialApp.router allows GoRouter to manage the application’s navigation state.

When the operating system delivers a supported deep link to Flutter, the routing system can navigate to the corresponding route.

The Android and iOS domain association configurations are still required for verified links to work.

8. Create a Product Detail Screen

Next, create a product detail screen that receives the product ID from the incoming URL.

Create:

lib/features/products/screens/product_detail_screen.dart

import 'package:flutter/material.dart';

class ProductDetailScreen extends StatelessWidget {
  final String productId;

  const ProductDetailScreen({
    super.key,
    required this.productId,
  });

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Product Details'),
      ),

      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,

          children: [
            const Text(
              'Product Detail Screen',
              style: TextStyle(
                fontSize: 20,
                fontWeight: FontWeight.bold,
              ),
            ),

            const SizedBox(height: 16),

            Text(
              'Product ID: $productId',
            ),
          ],
        ),
      ),
    );
  }
}

For this example, opening:

https://example.com/products/123

will display:

Product Detail Screen

Product ID: 123

In a real application, use the product ID to fetch the corresponding product information from your API, Firebase, Supabase, or local database.

Always validate the incoming ID and handle cases where the requested product does not exist.

9. Configure Android App Links

Now that Flutter can handle the product route, we need to configure Android to recognize URLs associated with your website.

Android App Links require two main configurations:

1. An intent filter in AndroidManifest.xml.
2. A Digital Asset Links file hosted on your website.

Both configurations must reference the correct application and domain.

Step 1: Open AndroidManifest.xml

Navigate to:

android/app/src/main/AndroidManifest.xml

Locate the MainActivity declaration inside the <application> element.

Add an App Links intent filter inside the activity.

<activity
    android:name=".MainActivity"
    android:exported="true"
    android:launchMode="singleTop"
    android:theme="@style/LaunchTheme"
    android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
    android:hardwareAccelerated="true"
    android:windowSoftInputMode="adjustResize">

    <meta-data
        android:name="flutter_deeplinking_enabled"
        android:value="true" />

    <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="example.com" />

    </intent-filter>

</activity>

This example shows the relevant activity configuration. Preserve the other existing Flutter activity settings, metadata, and launcher intent filter in your project.

Understanding the intent filter

The VIEW action indicates that the activity can handle requests to display data.

The DEFAULT category allows the activity to receive matching implicit intents.

The BROWSABLE category allows the activity to receive links originating outside the application, such as links opened from a browser.

The android:autoVerify="true" attribute requests Android App Links verification for the declared domain.

The <data> element specifies the HTTPS scheme and the website domain.

Replace example.com with your actual domain.

Step 2: Restrict links to specific paths

If your application should handle only product URLs, you can restrict the intent filter.

For example:

<data
    android:scheme="https"
    android:host="example.com"
    android:pathPrefix="/products/" />

This matches URLs beginning with:

https://example.com/products/

Other website URLs will not match this specific path rule.

If your application supports multiple URL patterns, configure the appropriate intent filters and website association rules.

Be careful when combining multiple <data> elements in one intent filter because Android may merge their attributes into additional combinations.

Use separate intent filters when necessary to express distinct URL patterns clearly.

10. Create the Android Digital Asset Links File

Android needs to verify that your website authorizes your application to handle its links.

This verification uses a JSON file named:

assetlinks.json

The file must be publicly accessible at:

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

Replace example.com with your actual website domain.

Example assetlinks.json

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.myapp",
      "sha256_cert_fingerprints": [
        "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
      ]
    }
  }
]

Replace the package name and certificate fingerprint with your actual Android application details.

The fingerprint shown above is only a placeholder.

Do not publish it as your application’s real signing certificate fingerprint.

Understanding the JSON configuration

The relation field declares that the website authorizes the specified Android application to handle its URLs.

The namespace identifies the target as an Android application.

The package_name must match your Android application’s actual application ID.

The sha256_cert_fingerprints array contains the SHA-256 fingerprint of the certificate used to sign the application.

All of these values must be configured correctly for domain verification to succeed.

11. Get Your Android SHA-256 Certificate Fingerprint

Android App Links verification depends on the application’s signing certificate.

You can obtain the certificate fingerprint using Java’s keytool utility.

Get the debug certificate fingerprint

For a standard Android debug keystore, run:

keytool -list -v \
  -keystore ~/.android/debug.keystore \
  -alias androiddebugkey \
  -storepass android \
  -keypass android

Find the SHA-256 value in the output.

Example:

SHA256: AA:BB:CC:DD:...

Copy the complete fingerprint into your assetlinks.json file.

Get the release certificate fingerprint

For an application signed using your own release keystore:

keytool -list -v \
  -keystore /path/to/release-keystore.jks \
  -alias your-key-alias

Replace the keystore path and alias with your actual signing configuration.

Important: Google Play App Signing

If your application uses Google Play App Signing, the certificate used to sign the APKs distributed through Google Play may differ from your local upload certificate.

For production App Links, obtain the appropriate app signing certificate fingerprint from Google Play Console.

Navigate to your application’s App integrity section and inspect the app signing certificate details.

Use the fingerprint corresponding to the certificate that signs the installed application.

You can include multiple valid fingerprints in the association file when necessary, such as when supporting debug and production builds.

Official documentation: https://developer.android.com/training/app-links/verify-android-applinks

12. Host and Verify assetlinks.json

Upload the assetlinks.json file to your website.

The final URL must be:

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

The file should be publicly accessible over HTTPS without authentication or redirects.

Serve it with the appropriate JSON content type.

You can check the response using:

curl -i \
  https://example.com/.well-known/assetlinks.json

Verify that the server returns a successful response and the expected JSON content.

Common hosting problems include incorrect file paths, redirects, missing files, and serving the association file from the wrong domain.

For example, if your application handles links from both example.com and www.example.com, configure and verify each host as required.

A file hosted only on example.com does not automatically establish an association for every subdomain.

13. Test Android App Links

After configuring the Android manifest and hosting the association file, install your application on an Android device.

You can test whether Android routes a URL to your application using ADB.

Open an App Link

Run:

adb shell am start \
  -a android.intent.action.VIEW \
  -c android.intent.category.BROWSABLE \
  -d "https://example.com/products/123"

If Android selects your application to handle the link, it should open the corresponding product screen.

However, this command alone does not prove that domain verification succeeded.

Recheck domain verification

On supported Android versions, request a verification check using:

adb shell pm verify-app-links --re-verify com.example.myapp

Then inspect the verification state:

adb shell pm get-app-links com.example.myapp

Replace com.example.myapp with your actual Android application ID.

The output can help you identify whether the domain has been verified or whether additional configuration is required.

For reliable production testing, install the correctly signed application and verify its association with the intended domain.

14. Configure iOS Universal Links

Android App Links and iOS Universal Links use different verification systems.

For iOS, you need to configure the Associated Domains capability and host an Apple App Site Association file.

The application must also be signed with the appropriate entitlements.

Step 1: Open the iOS project in Xcode

From your Flutter project directory, run:

open ios/Runner.xcworkspace

In Xcode, select the Runner target.

Navigate to:

Signing & Capabilities

Click:

+ Capability

Add:

Associated Domains

This capability allows the application to declare domains associated with its functionality.

Step 2: Add your website domain

Under Associated Domains, add:

applinks:example.com

If your application also handles links from the www subdomain, add:

applinks:www.example.com

Replace these values with your actual website domains.

Do not include https:// in the Associated Domains entry.

The applinks: prefix identifies the domain as supporting Universal Links.

Step 3: Verify the entitlements file

Xcode manages the Associated Domains entitlement in your application’s entitlements configuration.

A typical configuration looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<plist version="1.0">
<dict>
    <key>com.apple.developer.associated-domains</key>
    <array>
        <string>applinks:example.com</string>
    </array>
</dict>
</plist>

The entitlement must be included in the signed application.

Adding the domain to a local configuration file without the corresponding signing capability may not be sufficient.

15. Create the Apple App Site Association File

iOS uses an Apple App Site Association file, commonly called an AASA file, to verify the relationship between a website and an application.

The file is named:

apple-app-site-association

It does not have a .json extension.

Host it at:

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

Apple also supports the appropriate root-domain location for the association file.

Example AASA file

{
  "applinks": {
    "details": [
      {
        "appIDs": [
          "ABCDE12345.com.example.myapp"
        ],
        "components": [
          {
            "/": "/products/*",
            "comment": "Open product detail pages"
          },
          {
            "/": "/profile/*",
            "comment": "Open profile pages"
          }
        ]
      }
    ]
  }
}

Replace the example Team ID and Bundle ID with your actual values.

Understanding the AASA configuration

The appIDs array identifies the applications authorized to handle matching URLs.

Each application identifier combines the Apple application identifier prefix and Bundle ID.

For many applications, this prefix is the Apple Developer Team ID.

The components array specifies which URL patterns are eligible for Universal Links.

In this example, the application can handle URLs beginning with:

https://example.com/products/

and:

https://example.com/profile/

Other paths are not included in these rules.

You can configure additional patterns based on your application’s supported routes.

Official documentation: https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app

16. Host the AASA File Correctly

Upload the Apple App Site Association file to your website.

The final URL should be:

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

Make sure the file:

• Is publicly accessible through HTTPS.
• Contains valid JSON.
• Is served without a .json extension.
• Uses an appropriate JSON content type.
• Does not require authentication.
• Is available without HTTP redirects.

Test the response using:

curl -i \
  https://example.com/.well-known/apple-app-site-association

A successful response should return the association file’s JSON content.

Unlike Android’s assetlinks.json, the AASA file identifies the iOS application using its application identifier rather than an Android package name and signing certificate fingerprint.

Also, Apple’s association-file retrieval and caching behavior can affect how quickly configuration changes become available to installed applications.

For this reason, allow for propagation and retest after updating the association file.

17. Test Universal Links on iOS

After configuring Associated Domains and hosting the AASA file, build and install the application on an iOS device.

For reliable testing, use a physical iPhone with the correctly signed application.

Test using a link from another application

Send the following URL to yourself through Messages, Mail, or another application that supports opening Universal Links:

https://example.com/products/123

Tap the link.

If the association is valid and iOS selects the application, the Flutter app should open the product detail screen.

Test using Safari

Universal Links can behave differently depending on how the user opens the URL.

For example, tapping a link to the same domain while already browsing that domain in Safari may keep the user in Safari.

Therefore, test links from multiple contexts rather than relying only on typing a URL directly into Safari’s address bar.

Check the application configuration

If Universal Links do not work, verify that:

1. The Bundle ID matches the application identifier in the AASA file.
2. The correct Associated Domains entitlement is included in the signed application.
3. The website serves the AASA file successfully.
4. The URL path matches an allowed AASA component.
5. The installed application uses the intended signing configuration.
6. The user has not selected a preference that causes the link to remain in the browser.

You may also need to reinstall the application when testing changes to domain association configuration.

18. Handle App Links and Universal Links Using the app_links Package

GoRouter is useful when your application already uses declarative routing.

However, some Flutter applications use GetX, Navigator, or another custom navigation system.

In those cases, the app_links package provides an alternative way to receive incoming links.

Official package: https://pub.dev/packages/app_links

Install it using:

flutter pub add app_links

The package can provide the initial link that launched the application and a stream of incoming links received while the application is running.

Important configuration

When using app_links as your dedicated incoming-link handler, disable Flutter’s default deep-link handler to avoid conflicting navigation.

For Android, add the following metadata inside the MainActivity declaration:

<meta-data
    android:name="flutter_deeplinking_enabled"
    android:value="false" />

For iOS, add the following entry to ios/Runner/Info.plist inside the main dictionary:

<key>FlutterDeepLinkingEnabled</key>
<false/>

These settings are for the alternative plugin-based approach.

If you use GoRouter with Flutter’s default deep-link handling, keep the framework deep-link handler enabled instead.

19. Create a Reusable Deep Link Service

For a plugin-based implementation, create a service that receives and processes incoming URLs.

Create:

lib/core/services/deep_link_service.dart

import 'dart:async';

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

class DeepLinkService {
  final AppLinks _appLinks = AppLinks();

  StreamSubscription<Uri>? _subscription;

  Future<void> initialize({
    required void Function(Uri uri) onLink,
  }) async {
    _subscription ??= _appLinks.uriLinkStream.listen(
      onLink,
      onError: (error) {
        debugPrint(
          'Deep link error: $error',
        );
      },
    );

    final initialUri =
        await _appLinks.getInitialLink();

    if (initialUri != null) {
      onLink(initialUri);
    }
  }

  Future<void> dispose() async {
    await _subscription?.cancel();

    _subscription = null;
  }
}

This service receives incoming links and passes them to a callback.

The callback can then decide which application screen should open.

Avoid duplicate initial-link handling

The app_links package also provides incoming-link streams that may include the initial link, depending on the package version and API behavior.

If you use both the initial-link method and the incoming-link stream, ensure the same URL is not processed twice.

For example, you can track whether the initial link has already been handled or choose one consistent link-delivery strategy.

For a production application, initialize the link service early enough to receive startup links and wait until your navigation system is ready before processing them.

20. Navigate Using GetX

If your application uses GetX, you can process incoming links and navigate to the appropriate screen.

For example:

import 'package:get/get.dart';

void handleDeepLink(Uri uri) {
  if (uri.scheme != 'https' ||
      uri.host != 'example.com') {
    return;
  }

  final segments = uri.pathSegments;

  if (segments.length == 2 &&
      segments[0] == 'products') {
    final productId = segments[1];

    if (productId.isEmpty) {
      return;
    }

    Get.toNamed(
      '/product-details',
      arguments: {
        'productId': productId,
      },
    );
  }
}

The handler validates the URL’s scheme, host, and path before navigating.

For example:

https://example.com/products/123

will navigate to:

/product-details

with the following argument:

{
  'productId': '123',
}

Your GetX route configuration must define the destination route.

For example:

GetPage(
  name: '/product-details',
  page: () {
    final arguments =
        Get.arguments as Map<String, dynamic>;

    return ProductDetailScreen(
      productId: arguments['productId'] as String,
    );
  },
),

In a production application, validate route arguments and handle invalid or missing values gracefully.

Do not assume every incoming URL contains a valid product ID.

21. Handle Deep Links When the App Is Closed or Running

Deep links can arrive in different application states.

Your implementation should handle each state correctly.

Application state	Expected behavior
App not running	Launch the application and navigate to the requested content.
App in background	Bring the application to the foreground and process the incoming URL.
App in foreground	Navigate to the requested content without restarting the application.
User not authenticated	Complete authentication and then open the requested protected content.
Requested content unavailable	Display an appropriate error or fallback screen.

Handle startup initialization

A deep link may arrive before your application finishes initializing Firebase, local storage, authentication, or other required services.

If navigation occurs before the router is ready, the application may fail to open the requested screen.

For applications using GetX or manual navigation, store the incoming URI until initialization is complete.

Then process the pending link after the application’s navigation system is available.

For GoRouter applications, use routing redirects and application initialization state to manage protected or delayed navigation.

Avoid navigating immediately from an asynchronous callback when the required application state has not yet been initialized.

22. Handle Authentication-Protected Deep Links

Some deep links point to screens that require authentication.

For example:

https://example.com/profile/orders

If the user is already authenticated, the application can open the requested screen.

If the user is not authenticated, the application should redirect to the login screen and preserve the intended destination.

After successful authentication, the user can continue to the originally requested screen.

Example using GoRouter

final GoRouter appRouter = GoRouter(
  routes: [
    GoRoute(
      path: '/login',
      builder: (context, state) {
        return const LoginScreen();
      },
    ),

    GoRoute(
      path: '/profile/orders',
      builder: (context, state) {
        return const OrdersScreen();
      },
    ),
  ],

  redirect: (context, state) {
    final isLoggedIn =
        authController.isLoggedIn.value;

    final location =
        state.uri.path;

    final isLoginRoute =
        location == '/login';

    final isProtectedRoute =
        location.startsWith('/profile/');

    if (!isLoggedIn && isProtectedRoute) {
      final destination = Uri.encodeComponent(
        state.uri.toString(),
      );

      return '/login?redirect=$destination';
    }

    if (isLoggedIn && isLoginRoute) {
      final destination =
          state.uri.queryParameters['redirect'];

      if (destination != null &&
          destination.startsWith('/') &&
          !destination.startsWith('//')) {
        return destination;
      }

      return '/';
    }

    return null;
  },
);

This example demonstrates the redirect logic. It assumes that your application already provides authController, LoginScreen, and OrdersScreen.

In a real application, connect the router to your authentication state so redirects are reevaluated when the user logs in or logs out.

Also, validate redirect destinations against an allowlist of supported internal routes.

Do not allow an untrusted external URL to become an unrestricted post-login redirect.

23. Handle Query Parameters in Deep Links

Deep links may contain query parameters in addition to path parameters.

For example:

https://example.com/products/123?ref=summer-sale

The product ID identifies the requested product, while the ref parameter may indicate where the link originated.

You can access query parameters using GoRouter.

GoRoute(
  path: '/products/:id',

  builder: (context, state) {
    final productId =
        state.pathParameters['id']!;

    final referralSource =
        state.uri.queryParameters['ref'];

    return ProductDetailScreen(
      productId: productId,
    );
  },
),

If you use a dedicated link handler, access query parameters through the Uri object.

final Uri uri = Uri.parse(
  'https://example.com/products/123?ref=summer-sale',
);

final productId = uri.pathSegments.last;

final referralSource =
    uri.queryParameters['ref'];

Avoid placing sensitive information such as passwords, access tokens, or private user data in ordinary deep-link query parameters.

URLs may be stored in browser history, analytics systems, server logs, or shared messages.

24. Test Deep Links on Android and iOS

Deep-link testing should cover more than opening one URL while the application is running.

Test different application states, URL patterns, and authentication conditions.

Test case	Expected result
Open a valid product URL	Opens the correct product screen.
Open a valid URL while the app is closed	Launches the app and opens the requested content.
Open a URL while the app is running	Navigates without creating unnecessary duplicate screens.
Open an unsupported path	Displays a fallback or not-found screen.
Open a protected URL while logged out	Redirects to login and preserves the destination.
Open a URL for deleted content	Displays a content-unavailable message.
Open a URL from an unrelated domain	Does not treat it as a trusted application link.
Open a supported URL without the app installed	Opens the corresponding website when available.

Android testing command

adb shell am start \
  -a android.intent.action.VIEW \
  -c android.intent.category.BROWSABLE \
  -d "https://example.com/products/123"

iOS testing

Install the signed application on a physical device and open the Universal Link from Messages, Mail, or another supported application.

Also test the website fallback when the application is not installed.

Testing both native navigation and website behavior helps ensure that shared URLs remain useful for all users.

25. Common App Links and Universal Links Problems

Deep-link configuration involves Flutter routing, operating-system settings, application signing, and website hosting.

A problem in any of these areas can prevent links from opening correctly.

Problem 1: The link opens in the browser instead of the app

Possible causes include an unverified domain, an incorrect association file, a signing certificate mismatch, unsupported URL paths, or user link-handling preferences.

On Android, inspect the App Links verification state.

On iOS, verify the Associated Domains entitlement and AASA configuration.

Problem 2: Android App Links work in debug mode but not in production

The debug and release builds may use different signing certificates.

If your production application is distributed through Google Play, use the appropriate Play App Signing certificate fingerprint in assetlinks.json.

Also verify that the production application ID matches the package name declared in the association file.

Problem 3: Universal Links work on one iPhone but not another

Check the installed application version, iOS version, signing configuration, user preferences, and association-file availability.

Apple’s association-file caching can also affect testing after website configuration changes.

Reinstalling the application may help when testing updated association settings.

Problem 4: The app opens but displays the home screen

The operating system may be delivering the link correctly while Flutter is not processing the requested route.

Verify that your GoRouter route matches the incoming URL path.

If using a plugin, check that the incoming URI is received and processed after the navigation system is initialized.

Also verify that Flutter’s default deep-link handler and any plugin-based handler are not conflicting.

Problem 5: The same screen opens twice

Duplicate navigation can occur when the same incoming URL is processed by multiple handlers.

For example, an application may process the initial link manually and then receive the same URL through a link stream.

Choose a consistent link-handling strategy and prevent duplicate processing.

Problem 6: Links work only when the application is already open

This may indicate that your application handles incoming link events but does not correctly process startup links.

For plugin-based implementations, initialize the link handler early and handle the initial URI.

For router-based implementations, verify that the router can resolve the incoming route during application startup.

26. Security Best Practices for Deep Linking

Deep links originate outside your application and should be treated as untrusted input.

Even when a URL belongs to a verified domain, its path parameters and query parameters may contain unexpected values.

Follow these security practices:

• Validate the URL scheme, host, path, and parameters before processing incoming links.
• Require authentication for protected application screens.
• Verify authorization on the backend before returning private data.
• Avoid placing access tokens or sensitive information in ordinary URLs.
• Prevent unrestricted redirects to external websites.
• Handle invalid product IDs and unsupported routes safely.
• Use HTTPS for public App Links and Universal Links.
• Keep domain association files accurate and publicly accessible.
• Avoid logging sensitive query parameters.
• Test link handling with malformed and unexpected URLs.

Important: Opening a protected screen through a deep link must not bypass authentication or authorization checks.

For example, receiving an order ID through a URL does not mean the current user is authorized to view that order.

The backend must verify that the authenticated user has permission to access the requested resource.

27. Best Practices for Production Flutter Applications

A reliable deep-linking implementation should provide consistent navigation across Android, iOS, and the website.

For production applications, follow these recommendations:

• Use HTTPS-based App Links and Universal Links for public shared content.
• Maintain a consistent URL structure across the website and mobile application.
• Configure Android and iOS domain verification correctly.
• Use a centralized routing system or dedicated link handler.
• Avoid conflicting deep-link listeners.
• Handle startup, background, and foreground link delivery.
• Preserve intended destinations during authentication.
• Display appropriate fallback screens for unavailable content.
• Validate all incoming URL parameters.
• Test both debug and correctly signed production builds.
• Provide useful website content when the application is not installed.
• Monitor deep-link navigation failures after releasing application updates.

These practices help create a predictable experience for users opening content from websites, emails, messages, notifications, and shared URLs.

Frequently Asked Questions

What is the difference between deep links and App Links in Flutter?

Deep linking is the general concept of opening specific content inside an application through a URL.

Android App Links are a verified form of deep linking that uses HTTPS URLs and domain ownership verification.

iOS provides similar functionality through Universal Links.

Do I need Firebase Dynamic Links for Flutter deep linking?

No. Flutter can handle Android App Links and iOS Universal Links directly through its routing system or a compatible link-handling package.

Firebase Dynamic Links was shut down on August 25, 2025, so new implementations should use supported alternatives rather than depend on that service.

Can I implement App Links using GetX?

Yes. You can use the app_links package to receive incoming URLs and navigate using GetX.

Validate the incoming URL and ensure that the navigation system is ready before processing startup links.

Can I use GoRouter for Universal Links?

Yes. GoRouter supports URL-based navigation and can handle incoming Universal Links through Flutter’s routing system.

You still need to configure the iOS Associated Domains entitlement and host the correct Apple App Site Association file.

Do App Links work if the application is not installed?

If the application is not installed, a standard HTTPS URL can open the corresponding website.

This is one of the advantages of using web URLs for App Links and Universal Links.

The website must provide the appropriate content or fallback behavior.

Can I open a specific product screen using a URL?

Yes. Define a route such as /products/:id and configure your application to handle the corresponding HTTPS URL.

When the link is delivered to the application, extract the product ID and load the requested product.

Why are my Android App Links not verified?

Common causes include an incorrect package name, signing certificate fingerprint mismatch, missing assetlinks.json file, incorrect domain configuration, or an inaccessible association file.

Inspect the verification state using Android’s App Links debugging commands and verify the configuration for the installed application.

Why are Universal Links not working on iOS?

Check the Associated Domains entitlement, application identifier, AASA file, supported URL paths, and application signing configuration.

Also consider the context in which the user opens the link, because iOS does not always open the native application for every Universal Link tap.

Conclusion

Android App Links and iOS Universal Links allow Flutter applications to open specific screens directly from standard HTTPS URLs.

By configuring Android intent filters, Digital Asset Links, iOS Associated Domains, and the Apple App Site Association file, you can establish a verified relationship between your website and mobile application.

Flutter’s routing system, including GoRouter, can then process incoming URLs and navigate users to the appropriate screens.

For applications using GetX or custom navigation, the app_links package provides an alternative way to receive and handle incoming links.

A reliable implementation should also handle authentication, application lifecycle changes, invalid URLs, unavailable content, and website fallback behavior.

The key to successful deep linking is combining correct platform-level domain verification with reliable Flutter navigation and secure handling of incoming URLs.