Flutter SDK

• Flutter / Dart: SDK >=2.17.0 <4.0.0, Flutter >=2.10.0.
• Platforms: Android and iOS.
• API key: set natively, per platform — never hard-coded in Dart. You can create a key in App Settings.

Native key names

import 'package:flutter/material.dart';
import 'package:flutter_deeplinkly/flutter_deeplinkly.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  FlutterDeeplinkly.init();
  runApp(const MyApp());
}

The instance registers a WidgetsBindingObserver and forwards lifecycle changes to the native layer, and retries marking Flutter ready when the app resumes.

import 'dart:async';
import 'package:flutter/material.dart';
import 'package:flutter_deeplinkly/flutter_deeplinkly.dart';

class DeeplinklyBootstrap extends StatefulWidget {
  const DeeplinklyBootstrap({super.key, required this.child});

  final Widget child;
  @override
  State<DeeplinklyBootstrap> createState() => _DeeplinklyBootstrapState();
}

class _DeeplinklyBootstrapState extends State<DeeplinklyBootstrap> {
  StreamSubscription<Map<dynamic, dynamic>>? _sub;

  @override
  void initState() {
    super.initState();
    _sub = FlutterDeeplinkly.instance.deepLinkStream.listen(_onDeepLink);
  }

  void _onDeepLink(Map<dynamic, dynamic> payload) {
    final clickId = payload['click_id'] as String?;
    final params = payload['params'] as Map? ?? const {};
    // Normalize to your route model before navigating, and dedupe so a
    // resume does not navigate twice.
    debugPrint('Deeplinkly $clickId -> $params');
  }

  @override
  void dispose() {
    _sub?.cancel();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => widget.child;
}

Payload envelope — identical on Android and iOS

{
  'click_id': 'ab12…',            // null if the backend did not recognise the click
  'params': {'screen': 'home'},   // the link's own parameters
}

The deprecated FlutterDeeplinkly.onResolved API wraps the same stream; prefer deepLinkStream.listen for explicit subscription control and error boundaries.

<!-- android/app/src/main/AndroidManifest.xml -->
<activity android:name=".MainActivity" android:exported="true">
  <!-- App Links. The one that matters: it lets a tap on
       https://links.yourapp.com/abc123 open the app directly. Without it every
       link detours through the browser, and in-app browsers that block
       intent:// URLs (Instagram, Facebook, TikTok) never reach your app at all
       — even when it is installed. autoVerify only works on http/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="links.yourapp.com" />
  </intent-filter>

  <!-- Custom scheme: the browser fallback path. Keep it, but it is a
       fallback, not a substitute for the filter above. -->
  <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="yourapp" android:host="deeplink" />
  </intent-filter>
</activity>

<application ...>
  <meta-data
      android:name="com.deeplinkly.sdk.api_key"
      android:value="your_api_key_here" />

  <!-- Optional. Set it if the app App Links any host besides its Deeplinkly
       link domain. Comma separated. -->
  <meta-data
      android:name="com.deeplinkly.sdk.link_domains"
      android:value="links.yourapp.com" />
</application>

Replace links.yourapp.com with your Deeplinkly link domain, and yourapp with the URI scheme you set in the dashboard.

Which links the SDK claims

The rule is the same on both platforms. A link that came through the redirect carries a click_id, and the SDK acts on that whatever the scheme. The ambiguous case is the App Link / Universal Link bypass, where the OS routes https://links.yourapp.com/<code> straight to the app and the first path segment is the only thing to resolve on. So:

• Custom-scheme URLs without a click_id are ignored. Your own routes (yourapp://settings/notifications) are yours; the SDK will not resolve them.
• http(s) URLs are resolved by code. If the link-domains list is set, only those hosts are; without it every https link the app handles is.

Verifying App Links

Android checks https://<your-link-domain>/.well-known/assetlinks.json on install. Deeplinkly serves that file for you, but only once the dashboard has both your package name and your SHA-256 signing certificate fingerprint — with either missing the endpoint returns 404 and verification silently fails.

# Fingerprint from your release keystore. If you use Play App Signing, take it
# from Play Console → Test and release → Setup → App signing instead — Google
# re-signs the APK, so your upload fingerprint will not match what ships.
keytool -list -v -keystore <your-keystore> -alias <your-alias> | grep SHA256

# Confirm the file is live and verification passed.
curl https://links.yourapp.com/.well-known/assetlinks.json
adb shell pm get-app-links <your.package.name>

pm get-app-links should report verified for your domain. none or legacy_failure means the fingerprint does not match or the file is not reachable.

<!-- ios/Runner/Info.plist -->
<key>DeeplinklyApiKey</key>
<string>your_api_key_here</string>

<!-- Your Deeplinkly link domains. Subdomains count. Two jobs: the hosts a
     deferred link may be read from, and the hosts whose first path segment may
     be read as a link code. Set it if the app Universal Links any host besides
     its link domain. -->
<key>DeeplinklyLinkDomains</key>
<array>
  <string>yourbrand.deeplinkly.com</string>
</array>

<!-- Only if the project uses a custom scheme. -->
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>yourapp</string>
    </array>
  </dict>
</array>

Then add an Associated Domains capability with applinks:yourbrand.deeplinkly.com for each link domain, and make sure CODE_SIGN_ENTITLEMENTS actually points at the entitlements file.

The Deeplinkly interstitial copies the link when the visitor taps through to the store, and the SDK reads it back on first launch. There are two ways to read it back — pick one.

Option A — DeeplinklyPasteButton (recommended, no banner)

A system paste button rendered in your widget tree. Because the user taps it themselves, iOS treats the tap as the grant and shows no “Pasted from…” banner at all.

DeeplinklyPasteButton(
  onPasted: (handled) => setState(() => _showPasteButton = !handled),
  fallback: const SizedBox.shrink(),
)

Put it next to something like “Tapped a link to get here? Restore where you left off.” The recovered link arrives on deepLinkStream exactly like any other; onPasted only tells you whether the pasted content was one of your links. Requires iOS 16+, and renders fallback on Android and older iOS, so it is safe to place unconditionally.

Option B — automatic read (on by default, shows the banner)

On by default; you do not need to enable it. To turn it off:

<!-- Info.plist, not Dart: the read happens during plugin registration,
     before any Dart runs, so setCheckPasteboardOnInstall(false) is too late
     to prevent the first one. -->
<key>DeeplinklyCheckPasteboardOnInstall</key>
<false/>

To explain the prompt before it appears, turn the automatic read off in Info.plist and drive it yourself:

// Explain the prompt before it appears: turn the automatic read off in
// Info.plist, then drive it yourself.
if (await FlutterDeeplinkly.willShowPasteboardBanner()) {
  await showMyPrimingDialog();   // "we can restore where you left off"
  await FlutterDeeplinkly.checkPasteboardNow();
}

await FlutterDeeplinkly.setAttributionLevel(DeeplinklyAttributionLevel.reduced);

Each level is a strict subset of the one above. Deep link delivery works at every level, including none — this restricts reporting, not functionality. Resolving a link never sends anything describing the device, at any level.

To start restricted before any Dart runs (enrichment can be sent during plugin registration), set it natively:

<!-- ios/Runner/Info.plist -->
<key>DeeplinklyAttributionLevel</key>
<string>reduced</string>

<!-- AndroidManifest.xml, inside <application> -->
<meta-data android:name="com.deeplinkly.sdk.attribution_level"
           android:value="reduced" />

The SDK does not do probabilistic (“fingerprint”) matching. Device signals are collected for reporting, never to derive an identifier linking a click to an install — matching is deterministic, on the click id or the install referrer. Nothing describing the device is collected at click time, in the browser or the interstitial; all of it is in-app and post-install.

Hashing identifiers on the device

Off by default. With it on, the email, phone number and names given to setUserData are SHA-256 hashed on the device and plaintext never reaches Deeplinkly.

await FlutterDeeplinkly.setPIIHashingEnabled(true); // SHA-256 on device before sending
await FlutterDeeplinkly.isPIIHashingEnabled();     // off unless you turned it on

Nothing is hashed on the Dart side. The normalisation must match the service byte for byte or an erasure request stops finding the person it names, so there is one implementation per platform rather than a third here. Gender, country and date of birth are deliberately not hashed: their value ranges are small enough to reverse a digest by enumeration.

Privacy manifest (iOS)

The SDK ships PrivacyInfo.xcprivacy in its resource bundle, so you do not declare its API usage yourself. By default NSPrivacyTracking is false and it reads no IDFA, so it needs no NSUserTrackingUsageDescription. The SDK never calls requestTrackingAuthorization in any configuration — it reads the status your own prompt produced.

Advertising ID on Android (opt-in)

The SDK compiles against play-services-ads-identifier but does not bundle it — that library declares the AD_ID permission, which would then be added to every app embedding the SDK, including apps under Play's Families policy. To report advertising_id, add it yourself:

// android/app/build.gradle
dependencies {
    implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
}

Without it everything else works unchanged. The SDK declares only INTERNET.

IDFA on iOS (opt-in)

Set DeeplinklyEnableIDFA to true in Info.plist. The IDFA is then reported only while ATT status is already authorized — if you never prompt, nothing is collected, and that is the correct outcome rather than a bug. Enabling it makes your app a tracking app, so you must also merge the plugin's Resources/IDFA/PrivacyInfo.xcprivacy template, add NSUserTrackingUsageDescription, and call ATTrackingManager.requestTrackingAuthorization yourself.

await FlutterDeeplinkly.setUserData(
  userId: 'user_123',
  email: 'ada@example.com',
  phoneNumber: '+441234567890',
  firstName: 'Ada',
  lastName: 'Lovelace',
  city: 'London',
  country: 'GB',
); // false if any field was malformed, in which case nothing was stored

Every field is optional and each call merges, so you can supply an email at sign-up and an address at checkout. A malformed field rejects the whole call — nothing is stored — so a rejected call never leaves you guessing which of the values took.

The rules are enforced natively rather than in Dart, so a native-only integration gets the same answer this one does. These fields survive a reduced downgrade, because attribution levels gate what the SDK observes about a device and an email someone typed into your app is not an observation. At none nothing is sent.

• dateOfBirth: YYYY-MM-DD.
• gender: 'm' or 'f' — the only two values Meta's ge accepts. Anything else is refused rather than coerced.
• country: ISO-3166-1 alpha-2, for example 'US'.
• Every field has a maximum length, listed in the plugin’s SIGNALS.md.

Your own identifiers

customData carries identifiers Deeplinkly does not name — typically product-analytics ids such as a Mixpanel distinct id or a CleverTap id. Attach a new identifier anytime; no app release required.

await FlutterDeeplinkly.setUserData(
  userId: 'user_123',
  customData: {
    'mixpanel_distinct_id': 'd-8837',
    'clevertap_id': 'ct-4412',
  },
);

Up to 10 entries, keys up to 64 characters and values up to 256. The caps live in the native SDKs, so there is one implementation of the rule rather than three that can drift.

Erasing it

await FlutterDeeplinkly.clearUserData(); // erases everything setUserData and setUserId recorded
await FlutterDeeplinkly.setUserId(null); // clears only the id

This is not merely “stop sending”: the next enrichment carries each previously-set field as an empty value, which the service reads as null this column rather than not reported. The erasure is re-sent until it is delivered, so calling it on a device that is offline still takes effect once it is not.

final ok = await FlutterDeeplinkly.logEvent(
  'purchase',
  parameters: {
    'order_id': 'ord_42',
    'amount': 49.99,   // stays a number end to end, not "49.99"
    'currency': 'USD',
  },
);
if (!ok) {
  // Rejected by validation — see the limits below. No network call was made.
}

Validation

• Event name: non-empty, max 64 characters.
• At most 25 custom parameters. The SDK's own _dl_* keys do not count toward this, and passing a key with that prefix is rejected.
• Parameter keys: max 64 characters.
• Parameter string values: max 256 characters.
• List / Map values are stored as compact JSON; the 256 limit applies to that encoded form.
• num and bool keep their JSON types end to end — 49.99 is stored as a number, not "49.99".

A rejected event returns false and makes no network call. The DeeplinklyEventType enum provides standard names (for example DeeplinklyEventType.purchase.eventName → purchase); you can still use raw strings for custom funnels.

await FlutterDeeplinkly.logPurchase(
  value: 49.99,
  currency: 'USD',
  orderId: 'ord_42',
  quantity: 1,
  productId: 'sku_9',
);

Not a separate pipeline: it sends the event named purchase with value and currency set, so everything true of logEvent — the retry queue, the parameter limits, the device block — is true of this too.

value and currency are what Meta's Conversions API and Google's enhanced conversions both key off, so this one call feeds both without you having to match their spelling.

Rejected, sending nothing, if the value is negative or not finite (a refund is a different event, not a negative purchase), the currency is not three letters, the quantity is negative, or parameters contains any of value, currency, order_id, quantity or product_id — pass those as arguments instead.

1. DeeplinklyBootstrap widget (or an app service) owns the single StreamSubscription.
2. DeeplinklyRouter pure functions: Map → your sealed route class (e.g. ProductRoute(id)).
3. Navigation adapter one place that talks to Navigator or GoRouter / Router config.
4. Idempotency: ignore duplicate payloads with the same logical key (click id + path + query hash).

Trigger a custom scheme on a device or emulator with adb:

# Replace package with your applicationId
adb shell am start -a android.intent.action.VIEW \
  -d "yourapp://deeplink/product/123" com.your.app

Verify cold start (process killed) and warm start (app backgrounded) separately. Two constraints worth planning around:

• Android: the Install Referrer is unavailable on sideloaded builds — test deferred flows through Play internal testing.
• iOS: deferred deep linking cannot be tested on the Simulator (no App Store). The read is once per install and clears the pasteboard, so reinstall to retest — relaunching will not repeat it.