deeplink_sdk 1.0.5
deeplink_sdk: ^1.0.5 copied to clipboard
A comprehensive Flutter SDK for handling deep links on Android and iOS platforms with easy routing and configuration.
DeepLink SDK #
A comprehensive Flutter SDK for handling deep links on Android and iOS platforms with easy routing and configuration.
Features #
- π Universal Deep Link Support - Handle custom URL schemes, App Links (Android), and Universal Links (iOS)
- π£οΈ Advanced Routing - Pattern-based routing with parameter extraction
- π± Cross-Platform - Seamless integration for both Android and iOS
- π― Type-Safe Parameters - Extract and parse route parameters with type safety
- π Analytics Ready - Built-in observer pattern for tracking deep link events
- π§ Flexible Configuration - Customize allowed schemes, hosts, and error handling
- π Stream-Based - Real-time deep link updates via streams
- π§ͺ Easy Testing - Test deep links directly in your app
Installation #
Add deeplink_sdk
to your pubspec.yaml
:
dependencies:
deeplink_sdk: ^1.0.5
Then run:
flutter pub get
Platform Setup #
Android Setup #
- Add intent filters to your
AndroidManifest.xml
:
<activity
android:name=".MainActivity"
android:exported="true"
android:launchMode="singleTop">
<!-- Custom URL Scheme -->
<intent-filter>
<action android:name="android.intent.action.VIEW"/>
<category android:name="android.intent.category.DEFAULT"/>
<category android:name="android.intent.category.BROWSABLE"/>
<data android:scheme="myapp" android:host="example.com"/>
</intent-filter>
<!-- App Links (HTTPS) -->
<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>
- For App Links, add your Digital Asset Links file:
Create .well-known/assetlinks.json
on your server:
[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.example.yourapp",
"sha256_cert_fingerprints": ["YOUR_APP_SIGNING_CERTIFICATE_SHA256"]
}
}]
iOS Setup #
- Add URL schemes to
Info.plist
:
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLSchemes</key>
<array>
<string>myapp</string>
</array>
<key>CFBundleURLName</key>
<string>com.example.deeplink</string>
</dict>
</array>
- For Universal Links, add Associated Domains:
In Runner.entitlements
:
<key>com.apple.developer.associated-domains</key>
<array>
<string>applinks:example.com</string>
</array>
- Add your Apple App Site Association file:
Create apple-app-site-association
on your server:
{
"applinks": {
"apps": [],
"details": [{
"appID": "TEAMID.com.example.yourapp",
"paths": ["*"]
}]
}
}
Quick Start #
import 'package:flutter/material.dart';
import 'package:deeplink_sdk/deeplink_sdk.dart';
void main() {
runApp(MyApp());
}
class MyApp extends StatefulWidget {
@override
_MyAppState createState() => _MyAppState();
}
class _MyAppState extends State<MyApp> {
@override
void initState() {
super.initState();
_initializeDeepLinking();
}
Future<void> _initializeDeepLinking() async {
// Configure the SDK
final config = DeepLinkConfig(
defaultScheme: 'myapp',
defaultHost: 'example.com',
allowedSchemes: ['myapp', 'https'],
allowedHosts: ['example.com'],
enableLogging: true,
);
// Initialize
await DeepLinkHandler.instance.initialize(
config: config,
observers: [LoggingDeepLinkObserver()],
);
// Set context for navigation
DeepLinkHandler.instance._router.setContext(context);
// Register routes
DeepLinkHandler.instance.registerRoutes({
'/': _handleHome,
'/product/:id': _handleProduct,
'/user/:userId/profile': _handleUserProfile,
'/search': _handleSearch,
});
// Listen to deep links
DeepLinkHandler.instance.deepLinkStream.listen((deepLinkData) {
print('Received deep link: ${deepLinkData.uri}');
});
}
Future<bool> _handleHome(BuildContext context, RouteParams params) async {
// Navigate to home screen
Navigator.pushNamed(context, '/home');
return true;
}
Future<bool> _handleProduct(BuildContext context, RouteParams params) async {
final productId = params.pathParam('id');
// Navigate to product screen with ID
Navigator.pushNamed(context, '/product', arguments: productId);
return true;
}
Future<bool> _handleUserProfile(BuildContext context, RouteParams params) async {
final userId = params.pathParam('userId');
final tab = params.queryParam('tab') ?? 'posts';
// Navigate to user profile
Navigator.pushNamed(context, '/profile', arguments: {'userId': userId, 'tab': tab});
return true;
}
Future<bool> _handleSearch(BuildContext context, RouteParams params) async {
final query = params.queryParam('q');
// Navigate to search with query
Navigator.pushNamed(context, '/search', arguments: query);
return true;
}
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'DeepLink Example',
home: HomeScreen(),
);
}
}
Advanced Usage #
Route Patterns #
The SDK supports various route patterns:
- Exact match:
/home
- Path parameters:
/product/:id
- Capturesid
as a parameter - Multiple parameters:
/user/:userId/post/:postId
- Wildcard:
/settings/*section
- Captures everything after/settings/
Parameter Extraction #
Future<bool> handleRoute(BuildContext context, RouteParams params) async {
// Path parameters
String? id = params.pathParam('id');
int? numericId = params.pathParamAsInt('id');
// Query parameters
String? query = params.queryParam('q');
bool featured = params.queryParamAsBool('featured', defaultValue: false);
// Get all parameters
Map<String, String> allParams = params.allParameters;
return true;
}
Custom Observers #
Create custom observers to track deep link events:
class MyAnalyticsObserver extends DeepLinkObserver {
@override
void onDeepLinkReceived(DeepLinkData data) {
// Track in your analytics service
analytics.track('deep_link_received', {
'url': data.uri.toString(),
'source': data.source.toString(),
});
}
@override
void onDeepLinkHandled(DeepLinkData data) {
// Track successful handling
}
@override
void onDeepLinkFailed(DeepLinkData data, String error) {
// Track failures
}
}
Internal Navigation #
Navigate internally using deep links:
// Navigate to a route programmatically
await DeepLinkHandler.instance.navigateTo(
'/product/123',
parameters: {'ref': 'home', 'campaign': 'sale'},
);
Configuration Options #
final config = DeepLinkConfig(
defaultScheme: 'myapp',
defaultHost: 'example.com',
allowedSchemes: ['myapp', 'https', 'http'],
allowedHosts: ['example.com', 'app.example.com'],
handleInBackground: true,
enableLogging: true,
autoHandleAppLinks: true,
errorHandler: (url, error) {
// Custom error handling
print('Deep link error: $url - $error');
},
);
Testing Deep Links #
Android #
Test using ADB:
# Custom scheme
adb shell am start -W -a android.intent.action.VIEW -d "myapp://example.com/product/123"
# HTTPS link
adb shell am start -W -a android.intent.action.VIEW -d "https://example.com/product/123"
iOS #
Test using the Simulator or device:
# Custom scheme
xcrun simctl openurl booted "myapp://example.com/product/123"
# Universal link
xcrun simctl openurl booted "https://example.com/product/123"
In-App Testing #
The example app includes a testing interface to simulate deep links:
DeepLinkHandler.instance.handleDeepLink('myapp://example.com/product/123');
API Reference #
DeepLinkHandler #
The main class for handling deep links.
Methods:
initialize()
- Initialize the handler with configurationregisterRoutes()
- Register multiple routesregisterRoute()
- Register a single routehandleDeepLink()
- Manually handle a deep linknavigateTo()
- Navigate internally using deep linksaddObserver()
- Add an observer for deep link eventsremoveObserver()
- Remove an observerdispose()
- Clean up resources
DeepLinkConfig #
Configuration for the deep link handler.
Properties:
defaultScheme
- Default scheme for internal navigationdefaultHost
- Default host for internal navigationallowedSchemes
- List of allowed URL schemesallowedHosts
- List of allowed hostshandleInBackground
- Handle links when app is in backgroundenableLogging
- Enable debug loggingerrorHandler
- Custom error handler functionautoHandleAppLinks
- Automatically handle app/universal links
RouteParams #
Parameters extracted from a deep link.
Methods:
pathParam()
- Get a path parameterqueryParam()
- Get a query parameterpathParamAsInt()
- Get path parameter as integerqueryParamAsInt()
- Get query parameter as integerpathParamAsBool()
- Get path parameter as booleanqueryParamAsBool()
- Get query parameter as boolean
DeepLinkData #
Data about a received deep link.
Properties:
uri
- The full URIscheme
- URL schemehost
- URL hostpath
- URL pathqueryParameters
- Query parameters maptimestamp
- When the link was receivedsource
- Source of the deep link (external, internal, notification, etc.)
Troubleshooting #
Common Issues #
Deep links not working on Android:
- Ensure
android:exported="true"
is set on your MainActivity - Check that your intent filters are correctly configured
- Verify your Digital Asset Links file is accessible
Deep links not working on iOS:
- Ensure URL schemes are registered in Info.plist
- Check Associated Domains configuration
- Verify your Apple App Site Association file is accessible
- Make sure entitlements are properly configured
Routes not matching:
- Check that routes are registered before deep links are received
- Verify the route pattern matches the incoming URL path
- Ensure the context is set before routing
π§βπ» Authors & Contributors #
- Meet Bhanabhagwanwala β meeeet-dev
- Sanket Jariwala β sanketJariwala9464
- Bhargav Jariwala β BhargavJari
Contributing #
Contributions are welcome! Please feel free to submit a Pull Request.
License #
This project is licensed under the MIT License - see the LICENSE file for details.
Support #
For issues, questions, or suggestions, please file an issue on the GitHub repository.