smart_links 1.0.0

Production-grade deep linking for Android and Flutter Web with deferred install referrer support.

smart_links

Production-grade deep linking for Android and Flutter Web — App Links, custom schemes, web URLs, and deferred install attribution on Android via the Play Install Referrer API.

Platform	Support
Android	Yes
Flutter Web	Yes
iOS	No
Desktop	No

Links: pub.dev · Changelog · Example · Repository · Issues

---

Features

• Standard deep links: Android App Links, custom URI schemes, and Flutter Web path/hash URLs
• Deferred deep linking on Android — restore the marketing destination after install-from-Play-Store
• Lightweight queue until your router is ready (markReady())
• Duplicate suppression for noisy platform callbacks
• Single Dart API across Android and web

---

Installation

Add to pubspec.yaml:

dependencies:
  smart_links: ^1.0.0

flutter pub get

import 'package:smart_links/smart_links.dart';

Requirements: Flutter SDK >=3.0.0, Dart SDK ^3.10.1.

---

Quick start

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await SmartLink.initialize(enableLogs: kDebugMode);

  final initial = await SmartLink.initialLink;
  final deferred = await SmartLink.deferredLink;

  SmartLink.stream.listen((link) {
    // Navigate: link.path, link.param('id'), etc.
  });

  runApp(const MyApp());
}

// After splash / router / Firebase init:
SmartLink.markReady();

API

Method / getter	Description
SmartLink.initialize()	Wire platform channels and listeners (once).
SmartLink.initialLink	First link at cold start (or current web URL).
SmartLink.deferredLink	Install referrer link (Android only).
SmartLink.stream	All links (normal + deferred + web).
SmartLink.markReady()	Flush queued links after the app is ready.

SmartLinkData

link.path;           // e.g. /product/42
link.queryParams;    // Map<String, String>
link.uri;            // Full Uri
link.isDeferred;     // true for install referrer
link.source;         // appLink | customScheme | deferredInstall | web | unknown

link.param('campaign');
link.paramInt('id');
link.hasParam('ref');

---

Queue behavior

Deep links often arrive before your router, splash screen, or Firebase finishes initializing. Links are queued until you call:

SmartLink.markReady();

Queued links are then replayed on SmartLink.stream once, without duplicate replay.

---

Android setup

1. AndroidManifest.xml (host app)

Custom 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" />
</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="www.yourdomain.com"
        android:pathPrefix="/" />
</intent-filter>

Host your Digital Asset Links file at:

https://www.yourdomain.com/.well-known/assetlinks.json

Use singleTop launch mode on your main activity so onNewIntent delivers background links.

2. Test with adb

adb shell am start -a android.intent.action.VIEW \
  -d "myapp://product/42?campaign=summer"

---

Deferred deep linking (Android)

Flow

1. User taps a marketing link while the app is not installed.
2. Your web or backend redirects to the Play Store with an encoded referrer payload.
3. User installs and opens the app.
4. The plugin reads the Install Referrer once, restores the deep link, and emits it on the same stream.
5. Consumed state is stored in SharedPreferences so it is not replayed on every launch.

Payload format

JSON (optionally Base64 URL-safe encoded):

{
  "path": "/product/42",
  "params": {
    "campaign": "summer"
  },
  "timestamp": 1234567890
}

Encode in Dart:

final payload = SmartLinkParser.encodeReferrerPayload(
  path: '/product/42',
  params: {'campaign': 'summer'},
);

Play Store URL

Pass the payload via the referrer query parameter (or inside utm_content):

https://play.google.com/store/apps/details?id=YOUR.PACKAGE.NAME
  &referrer=utm_content%3D<URL_ENCODED_PAYLOAD>

The native layer looks for utm_content, referrer, or payload keys in the install referrer string.

Requirements

• Dependency: com.android.installreferrer:installreferrer (included in this plugin)
• Referrer is fetched once per install; a consumed flag prevents repeat delivery
• Malformed JSON or Base64 errors are swallowed — the app does not crash

---

Flutter Web setup

No native plugin registration is required on web. The package listens to:

• Path URLs — https://yourapp.com/product/42
• Hash URLs — https://yourapp.com/#/product/42

On initialize(), the current browser URL is exposed as initialLink and further navigations emit on stream.

For path-based routing, configure your host and flutter build web URL strategy as usual (PathUrlStrategy if not using hash routing).

cd example
flutter run -d chrome

Change the browser URL to see events on the stream.

---

Example app

git clone https://github.com/vkashegde/smart_links.git
cd smart_links/example
flutter run

The demo shows initial and deferred links, queue + Mark ready, sample adb commands, and a sample Play Store referrer string. See example/README.md.

---

Troubleshooting

Issue	What to check
No App Link on Android	autoVerify="true", correct host, assetlinks.json, HTTPS
Link opens browser, not app	Domain verification failed or intent-filter host mismatch
Duplicate navigations	Call markReady() once; dedupe window is 2s
Deferred link missing	Install from a referrer URL; clear app data only to retest
Deferred fires every launch	Should not happen — consumed flag in SharedPreferences
Web stream silent	Call initialize(); use hash or path change / popstate
iOS / desktop	Not supported by design

---

Architecture

lib/
  smart_link.dart           # Public API
  smart_link_data.dart      # Model
  smart_link_source.dart    # Enum
  smart_link_parser.dart    # URI + referrer parsing
  smart_link_queue.dart     # Pre-ready queue
  smart_link_platform.dart  # Android MethodChannel / EventChannel
  smart_link_web.dart       # Web URL listener
android/                    # Kotlin Install Referrer + intents
example/                    # Demo app

---

Contributing

Bug reports and pull requests are welcome on GitHub.

---

License

MIT — see LICENSE.