Flutter SDK

Overview

The LinkSense Flutter plugin is a thin Dart facade over the native iOS and Android SDKs. It does no attribution logic itself — every public method is a typed passthrough that invokes a native bridge over MethodChannel + EventChannel. You get the same capabilities as the native SDKs from a single Dart API:

• Install-time attribution via the underlying iOS and Android SDKs.
• Deferred deep linking — exposed as a Dart Stream<Uri?>.
• Universal Link / App Link forwarding — Android App Links auto-forward via the plugin's ActivityAware integration; iOS Universal Links flow through handleUniversalLink().
• Link CRUD — async Future-returning create / read / update / delete.

Prerequisites

• Flutter 3.24 or later (Swift Package Manager support)
• iOS 14.0+ deployment target, Android minSdk 24
• An SDK key from your LinkSense project (Project Settings → SDK Keys)
• Universal Links / App Links configured for your project subdomain (see iOS Deep Linking and Android Deep Linking)

Installation

Add the plugin from pub.dev:

flutter pub add linksense

Platform Setup

iOS — the plugin pulls the native iOS SDK over Swift Package Manager. Make sure SPM is enabled in your Flutter toolchain (default in Flutter 3.27+):

flutter config --enable-swift-package-manager

Android — the plugin resolves the native Android SDK from Maven Central automatically; no extra Gradle changes are required beyond having mavenCentral() in your repositories block.

Configuration

Call configure, subscribe to the deferred deep link stream, then call start — typically in your main() before runApp:

import 'package:linksense/linksense.dart';
 
Future<void> bootstrap() async {
  await LinkSense.instance.configure(const LinkSenseConfiguration(
    sdkKey: 'ls_sdk_<project>_<random>',
    enableClipboard: false,
  ));
 
  LinkSense.instance.deferredDeepLinks.listen((uri) {
    if (uri != null) appRouter.handle(uri);
  });
 
  await LinkSense.instance.start();
}

Configuration fields:

Handling Deferred Deep Links

Deferred deep links are exposed as a Dart Stream<Uri?> on LinkSense.instance.deferredDeepLinks. Subscribe before calling start() to avoid missing the first emission. The stream emits both deferred (cold-start) and Universal Link (warm-path) URLs.

Forwarding Universal Links

On iOS, forward any NSUserActivity-style URL you receive from your routing layer through handleUniversalLink. The resolved URI is delivered through the same deferredDeepLinks stream.

// iOS only. No-op on Android.
await LinkSense.instance.handleUniversalLink(incomingUri);

On Android, this method is a no-op — App Link intents are auto-forwarded by the plugin's native side, so calling it from cross-platform code is harmless.

Link CRUD

The SDK exposes createLink, getLink, updateLink, and deleteLink as Future-returning methods. Any failure is thrown as a typed LinkSenseException — see Error Handling below.

final link = await LinkSense.instance.createLink(
  CreateLinkOptions(
    name: 'Summer sale',
    desktopUrl: Uri.parse('https://example.com/sale'),
    iosFallbackUrl: Uri.parse('https://apps.apple.com/app/id123456789'),
    androidFallbackUrl: Uri.parse(
      'https://play.google.com/store/apps/details?id=com.example.myapp',
    ),
  ),
);
print('Created: ${link.url}');

await LinkSense.instance.updateLink(
  'ln_abc123',
  UpdateLinkOptions(
    name: 'Renamed link',
    iosFallbackUrl: linkSenseClear, // explicitly null on the server
    // androidFallbackUrl omitted — leaves the server value untouched
  ),
);

Error Handling

Every public method translates native PlatformExceptions into a sealed LinkSenseException hierarchy. Use Dart's typed on … catch clauses:

try {
  final link = await LinkSense.instance.getLink('ln_abc123');
  // use link
} on LinkSenseNotConfigured {
  print('Call configure() first');
} on LinkSenseInvalidInput catch (e) {
  print('Field errors: ${e.fieldErrors}');
} on LinkSenseRateLimited catch (e) {
  print('Retry after ${e.retryAfterSeconds}s');
} on LinkSenseException catch (e) {
  print('SDK error: ${e.code}');
}

Typed subclasses: LinkSenseNotConfigured, LinkSenseInvalidSdkKey, LinkSenseNetworkException, LinkSenseDecodeFailure, LinkSenseUnauthorized, LinkSenseForbiddenCrossScope, LinkSenseForbiddenField, LinkSenseInvalidInput (carries fieldErrors), LinkSenseNotFound, LinkSenseCustomPathExists, LinkSenseRateLimited (carries retryAfterSeconds), LinkSenseServerException (catch-all).

Example & Resources

The pub.dev package includes a working Flutter sample under example/ covering configuration, deferred deep link handling, and link CRUD on both platforms.