👋 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
- Step 1: Add Required Package
- Step 2: Domain Verification Setup
- Step 3: Configure Deep Linking
- Step 4: Handle Deep Link Redirection in Flutter
- Step 5: Testing Deep Links
# 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.
SOCIAL SHARE CARD GENERATOR