deeplink_sdk 1.0.5 copy "deeplink_sdk: ^1.0.5" to clipboard
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 #

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

  1. 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>
  1. For Universal Links, add Associated Domains:

In Runner.entitlements:

<key>com.apple.developer.associated-domains</key>
<array>
    <string>applinks:example.com</string>
</array>
  1. 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 - Captures id 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');
  },
);

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 configuration
  • registerRoutes() - Register multiple routes
  • registerRoute() - Register a single route
  • handleDeepLink() - Manually handle a deep link
  • navigateTo() - Navigate internally using deep links
  • addObserver() - Add an observer for deep link events
  • removeObserver() - Remove an observer
  • dispose() - Clean up resources

DeepLinkConfig #

Configuration for the deep link handler.

Properties:

  • defaultScheme - Default scheme for internal navigation
  • defaultHost - Default host for internal navigation
  • allowedSchemes - List of allowed URL schemes
  • allowedHosts - List of allowed hosts
  • handleInBackground - Handle links when app is in background
  • enableLogging - Enable debug logging
  • errorHandler - Custom error handler function
  • autoHandleAppLinks - Automatically handle app/universal links

RouteParams #

Parameters extracted from a deep link.

Methods:

  • pathParam() - Get a path parameter
  • queryParam() - Get a query parameter
  • pathParamAsInt() - Get path parameter as integer
  • queryParamAsInt() - Get query parameter as integer
  • pathParamAsBool() - Get path parameter as boolean
  • queryParamAsBool() - Get query parameter as boolean

DeepLinkData #

Data about a received deep link.

Properties:

  • uri - The full URI
  • scheme - URL scheme
  • host - URL host
  • path - URL path
  • queryParameters - Query parameters map
  • timestamp - When the link was received
  • source - 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 #

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.

3
likes
160
points
225
downloads

Publisher

verified publishervioletwaves.in

Weekly Downloads

A comprehensive Flutter SDK for handling deep links on Android and iOS platforms with easy routing and configuration.

Repository (GitHub)
View/report issues

Topics

#deeplink #deep-linking #navigation #routing #universal-links

Documentation

Documentation
API reference

License

MIT (license)

Dependencies

flutter, meta, plugin_platform_interface

More

Packages that depend on deeplink_sdk

Packages that implement deeplink_sdk