# Deferred Deep Linking in Flutter: One Callback for iOS and Android

> Deferred deep linking Flutter guide: route the first open after install with one WarpLink 1.3.0 callback, plus first-open test steps and confidence scoring.

_Last updated: 2026-11-02_

> **TL;DR:** Deferred deep linking in Flutter carries a tapped link through an app store install and delivers it on first launch. Android reads the Play Install Referrer for an exact match, and iOS matches the install probabilistically. Both arrive in one Dart `onLink` callback, and `matchGuaranteed` tells you which.

Deferred deep linking in Flutter lets a user tap a link, install your app from the App Store or Play Store, and still land on the right screen on first launch. Flutter's own deep link handling cannot do this, because it reports a URL the OS handed your app and a fresh install has no URL to hand over. The work happens in two halves instead: the click is recorded at the edge with the signals a browser exposes, and on first launch the native SDK collects the device's own signals so the server can match the install back to that click. The two platforms get there differently. Android reads the Play Install Referrer for a deterministic match, while a genuine first install on iOS falls back to a probabilistic match. Both surface through one Dart callback, where `deepLink.isDeferred` is `true` and `matchGuaranteed` tells you whether the match was deterministic or probabilistic. With `warplink_flutter` 1.3.0 that is one `WarpLink.configure(apiKey:, onLink:)` call and no per-platform branch. The rest of this guide is the mechanism, the Dart, and the testing. For the cross-platform overview, see [deferred deep linking](https://warplink.app/deferred-deep-linking), and for how it differs from a standard link, see [deep link vs deferred deep link](https://warplink.app/blog/deep-link-vs-deferred-deep-link).

## The Minimal End-to-End Example

This is the whole integration for the first open after an install, written against `warplink_flutter` 1.3.0. Each part is explained further down.

```bash
flutter pub add warplink_flutter
```

```dart
// lib/main.dart
import 'dart:async';

import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:warplink_flutter/warplink_flutter.dart';

void main() => runApp(const App());

class App extends StatefulWidget {
  const App({super.key});

  @override
  State<App> createState() => _AppState();
}

class _AppState extends State<App> {
  @override
  void initState() {
    super.initState();
    unawaited(
      WarpLink.configure(
        apiKey: 'wl_live_yoursdkkeyhere000000000000000000', // an SDK key, from Keys > SDK keys
        debugLogging: kDebugMode,
        onLink: (event) {
          switch (event) {
            case LinkEvent(:final deepLink) when deepLink.isDeferred:
              // First open after install. matchGuaranteed is false for an iOS probabilistic match.
              debugPrint(
                '${deepLink.linkId} ${deepLink.matchType?.name} ${deepLink.matchConfidence}',
              );
              // Route it once the navigator exists (see the routing section).
            case LinkEvent():
              // A tap on a link while the app was installed.
              break;
            case ErrorEvent(:final error):
              debugPrint('WarpLink ${error.wireCode}: ${error.message}');
          }
        },
      ),
    );
  }

  @override
  Widget build(BuildContext context) => const MaterialApp(home: Placeholder());
}
```

`configure()` starts the deferred check on its own. The native SDK records the install, the server matches it to the click, and a match arrives in `onLink` with `isDeferred` set to `true`. No other call is required for the first open. The sections below add the platform setup, the navigation routing, and the testing steps that keep the result correct.

## Why Flutter Has No Deferred Deep Linking API

Flutter gives you one door for incoming links, and it is the deep link handler the framework wires to the platform. It forwards a URL to your router as a route, and between that and the plugins built on it you cover every link that arrives while your app exists on the device.

That last clause is the whole problem. Every one of those paths is a reporter: it tells you about a URL the operating system already routed into your process, and the OS only routes a URL into a process that is installed and registered for that host. When the user taps your link without the app, there is no process, no registration, and no URL event. iOS sends them to the App Store, Android sends them to the Play Store, and the link's destination stops there. The user installs, opens the app, and the launch link is `null`, not because anything failed but because nothing was delivered.

Deferred deep linking is the workaround for a delivery channel that does not exist. Instead of transporting the link through the install, it records the click on one side, records the install on the other, and matches the two afterwards. This is also why no router configuration fixes it: a `go_router` route table is a URL-to-screen mapping, and there is no URL. The deferred result arrives as a plain object from a native SDK, so it is your code, not the router, that routes it.

## Two Platform Mechanisms Under One Dart API

Cross-platform deferred linking is interesting in Flutter because iOS and Android solve the same problem with different machinery, and you want one code path on top of both. The plugin adds no signal of its own. The native iOS and Android SDKs collect everything, so attribution in a Flutter app is identical to a native app.

### Android: the Play Install Referrer

Android has a real answer. A redirect to the Play Store can attach a referrer string that the Play Store carries through the install and hands to the app afterwards. WarpLink sets that referrer to `utm_source=warplink&utm_content={link_id}`, so on first launch the native Android SDK reads it, sees the link id in plain text, and reports a deterministic match with confidence 1.0.

No inference and no window: the referrer names the click. This is why a test that works on Android tells you very little about how the same flow behaves on iPhone.

For a sideloaded `adb install` or direct APK, a device without Google Play Services, or expired referrer data, the Android SDK uses the same probabilistic match the iOS SDK uses, with no code change on your side.

### iOS: a probabilistic match, with the IDFV for repeat checks

For ordinary links, iOS has no referrer. The App Store passes nothing through the install, so there is no exact first-install signal. Referral links add a confirmation step, described below. The SDK still sends the Identifier for Vendor whenever iOS provides one: it is stable across all apps from the same vendor on a device and exempt from App Tracking Transparency. When iOS returns no value, for example after a restart before the first unlock, the field is left out and the check runs on the match key alone. The IDFV answers the same install asking again with the result that install already got, its match type and its confidence unchanged, so it never turns a probabilistic match into into a guaranteed match. The server skips the IDFV replay when the request is flagged `is_reinstall`. A reinstall gets a new check and falls through to the probabilistic match, so it is recorded as a new install.

The probabilistic tier compares signals captured when the link was tapped in the browser against signals collected when the app first launched: the IP address, the normalized primary language, and the timezone. The SDK sends the language and the timezone, the IANA zone name and the minute offset. It never sends the IP, because an app cannot see its own public address, so the server derives it from the request on both the click and the install side. Computing both halves in the same place is the only way the two hashes can agree.

### Referral links on iOS and Android

SDK 1.2.0 adds referral links. On Android the SDK reads `wl_rt` from the same Play referrer with no code change. On iOS the person pastes the invitation into a field on your onboarding screen, and you pass the text to `WarpLink.redeemInvitation(text)`. A confirmed invitation is an exact match, and it returns `null` when nothing is confirmed, so onboarding is never gated. The SDK never reads the clipboard. After sign-up, `WarpLink.claimReferral(installerId)` credits the install, and your backend receives a signed `referral.claimed` webhook. See the [Flutter attribution docs](https://warplink.app/docs/sdks/flutter/attribution) and the [referrals guide](https://warplink.app/docs/guides/referrals).

### The single Dart surface

Neither mechanism leaks into your code. Both platforms return the same `WarpLinkDeepLink` through the same callback, and the only thing that differs by platform is the confidence in it:

| Property | Type | Meaning |
|---|---|---|
| `linkId` | `String` | Identifier of the link in the dashboard |
| `destination` | `String` | The web destination URL |
| `deepLinkUrl` | `String?` | The in-app URL for this OS, or `null` when the link has none |
| `customParams` | `Map<String, Object?>` | The destination URL's query parameters on a tap, always empty on a deferred match |
| `isDeferred` | `bool` | `true` for an install match, `false` for a tap |
| `matchType` | `MatchType?` | `MatchType.deterministic`, `MatchType.probabilistic`, or `null` |
| `matchConfidence` | `double?` | Confidence from 0 to 1, or `null` when not matched |
| `matchGuaranteed` | `bool` | `true` only for a deterministic match |

`isDeferred` separates an install match from an ordinary tap. `matchGuaranteed` is what you branch on when the routing decision matters. Everything else is payload. A link resolved by a tap has `isDeferred: false`, a confidence of 1.0, and `matchGuaranteed: true`, so one routing function can serve both.

### iOS and Android side by side

| Install path | How the match is made | `matchType` | `matchConfidence` | `matchGuaranteed` |
|---|---|---|---|---|
| Android, installed from the Play Store | The Play Install Referrer names the click | `deterministic` | 1.0 | `true` |
| Android, sideloaded or no Google Play Services | Probabilistic match: IP address, language, timezone | `probabilistic` | Up to 0.85 inside the first hour | `false` |
| iOS, first install from the App Store | Probabilistic match: IP address, language, timezone | `probabilistic` | Up to 0.85 inside the first hour | `false` |
| iOS, referral link with the paste step | The person pastes the invitation with `redeemInvitation` | `deterministic` | 1.0 | `true` |
| iOS, the same install asks again | The IDFV returns the earlier answer | Unchanged | Unchanged | Unchanged |

## The Confidence Model and What to Trust

A deterministic match, which today means the Play Install Referrer on Android, returns `matchConfidence` of 1.0, `matchType` of `deterministic`, and `matchGuaranteed` set to `true`. A probabilistic match returns a score that decays with the gap between click and install, and `matchGuaranteed` stays `false`.

The probabilistic ceilings depend on the match key variant. Current SDKs send the IANA zone name, for example `America/Toronto`, which is the `enriched_tz` variant. Older SDKs send the minute offset instead, the `enriched` variant. When neither is usable, `basic` keys on IP and language alone.

| Time since click | `enriched_tz` | `enriched` | `basic` |
|------------------|---------------|------------|---------|
| < 1 hour | 0.85 | 0.80 | 0.70 |
| < 3 hours | 0.65 | 0.60 | 0.50 |
| < 6 hours | 0.50 | 0.45 | 0.35 |
| < 24 hours | 0.30 | 0.25 | 0.20 |

The zone name earns the higher ceiling because it carries far more entropy than the offset, roughly 340 zones against 38 offsets, and does not shift at a daylight saving boundary.

Two multipliers then reduce whichever ceiling applied, and they only ever reduce it. More than one claimable click sharing the match key applies x0.6. The click's IP address applies x0.6 for carrier grade NAT or a private address, x0.9 for a household IPv4 address, and x1.0 for IPv6.

The match window is set per link in the dashboard, not in the SDK. The default is 6 hours, set per link, up to 24 hours. The deterministic branches are unaffected by it.

Inside the first hour, probabilistic matching is strong.

The practical rule that falls out of this: `matchGuaranteed` and the confidence score tell you which destination to pick. A probabilistic match chooses content, so route it to a public destination with a safe fallback. Confidence is the second routing decision, and it only applies once `matchGuaranteed` is false: route to specific public content above 0.5, soften below it. Authenticate the user and check authorization separately before anything sensitive, whether or not the match was guaranteed.

## Wiring It Up: One Call, Both Platforms

The setup is four steps, each shown below:

1. Run `flutter pub add warplink_flutter`, and set `minSdk` to 26 on Android.
2. Create an SDK key under **Keys** > **SDK keys** in the dashboard.
3. Call `WarpLink.configure(apiKey: ..., onLink: ...)` once at startup.
4. `onLink` receives a `WarpLinkEvent`. On a `LinkEvent`, route on `deepLink.isDeferred`, `matchType`, and `matchConfidence`.

The package is `warplink_flutter` 1.3.0, published on pub.dev under the verified publisher `warplink.app`, MIT licensed with no third party runtime dependencies. It needs Flutter 3.38 or newer, Dart 3.10 or newer, iOS 15 or newer, and Android API 26 or newer. The SDK targets iOS and Android.

```bash
flutter pub add warplink_flutter
```

The iOS side comes through Swift Package Manager. Flutter 3.44 and later enable it by default. On Flutter 3.38 to 3.43, run this once on the machine that builds the app:

```bash
flutter config --enable-swift-package-manager
```

There is no Podfile change. On Android, set `minSdk` to 26 in `android/app/build.gradle.kts`, because Flutter's default can be lower and the manifest merge then fails:

```kotlin
android {
    defaultConfig {
        minSdk = 26
    }
}
```

Then call `configure()` once at startup, from the `initState` of your root widget, and detach the future with `unawaited`. Put the routing in its own function, so the callback stays short:

```dart
// lib/warplink_setup.dart
import 'dart:async';

import 'package:flutter/foundation.dart';
import 'package:warplink_flutter/warplink_flutter.dart';

import 'deferred_navigation.dart';

void startWarpLink() {
  unawaited(
    WarpLink.configure(
      apiKey: 'wl_live_yoursdkkeyhere000000000000000000',
      onLink: (event) {
        switch (event) {
          case LinkEvent(:final deepLink):
            // Cold start, warm start, or a deferred install match.
            routeLink(deepLink);
          case ErrorEvent(:final error):
            debugPrint('WarpLink ${error.wireCode}: ${error.message}');
        }
      },
    ),
  );
}
```

That single call wires three sources into one callback: cold start (launched by a link), warm start (foregrounded by a link), and the deferred check. `deepLink.isDeferred` tells the third apart from the first two.

Three behaviors of `configure()` are worth knowing before you debug anything. It does not throw on a malformed key: it checks the format before any native call, reports a bad one through `onLink` as an `ErrorEvent` with code `E_INVALID_API_KEY_FORMAT`, prints a warning, and leaves the SDK unconfigured. An exception thrown by your own `onLink` while `configure` delivers a rejected key or a configuration error propagates out of the future it returns, and an exception thrown for a link that arrives later surfaces as an uncaught error and does not stop the SDK. And the future completes when native configuration completes. It does not wait for the first cold-start or deferred delivery.

Either automatic piece can be disabled and driven yourself:

```dart
await WarpLink.configure(
  apiKey: 'wl_live_yoursdkkeyhere000000000000000000',
  automaticDeepLinks: false,          // wire onDeepLink / getInitialDeepLink yourself
  automaticDeferredDeepLinks: false,  // call checkDeferredDeepLink yourself
);
```

Note the asymmetry. Omitting `onLink` does not switch the deferred check off, because that request is what attributes the install. Only `automaticDeferredDeepLinks: false` stops it. Use an **SDK key**, created under **Keys** > **SDK keys** in the dashboard. An API key passes the format check and resolves deep links, but it cannot record installs, so attribution stays empty.

### Native host setup, and what deferred matching does not need

Setup for tapped links is configuration only, and none of it is required for deferred matching. Separate them so you debug the right layer.

On iOS, add the Associated Domains entry for your app's link host, `applinks:yourapp.aplnk.to`, to the Runner target. On Android, add an `autoVerify` intent filter for the same host inside your main `<activity>`, and keep the `android:launchMode="singleTop"` that `flutter create` writes, so a link tapped while the app runs reaches the running activity. You edit no `AppDelegate`, `SceneDelegate`, or `MainActivity`. The [Flutter deep linking guide](https://warplink.app/blog/flutter-deep-linking) walks through each file, including switching off Flutter's own deep-linking flag so your router does not also receive the URL.

The deferred path runs from `configure()` straight to the attribution endpoint. A missing entitlement breaks tapped Universal Links while deferred matching keeps working, and a missing launch mode breaks warm start the same way. If your deferred link is fine but a tapped one is not, the native host setup is where to look.

Declare your own domain, if you serve links from one, so the SDK recognizes it on the first launch, before it has fetched your domain list and even with no network:

```dart
await WarpLink.configure(
  apiKey: 'wl_live_yoursdkkeyhere000000000000000000',
  linkDomains: ['links.yourapp.com'],
  onLink: (event) {
    if (event case LinkEvent(:final deepLink)) routeLink(deepLink);
  },
);
```

Your app's own subdomain on `aplnk.to` needs no declaration. A custom domain also needs `applinks:links.yourapp.com` in the Associated Domains and a second `<data>` host in the intent filter, and it must be verified and live in the dashboard.

## The Manual Check and the Splash Gate

The automatic dispatch is right for most apps, with one exception: when your first screen depends on the answer and you would rather hold a splash than render onboarding and then yank it away. Disable the automatic deferred dispatch and await the check yourself. `checkDeferredDeepLink()` returns `Future<WarpLinkDeepLink?>`, resolving to `null` when there was no match.

```dart
// lib/splash_gate.dart
import 'dart:async';

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

import 'deferred_navigation.dart';

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

  final Widget child;

  @override
  State<SplashGate> createState() => _SplashGateState();
}

class _SplashGateState extends State<SplashGate> {
  bool _ready = false;

  @override
  void initState() {
    super.initState();
    unawaited(_check());
  }

  Future<void> _check() async {
    try {
      await WarpLink.configure(
        apiKey: 'wl_live_yoursdkkeyhere000000000000000000',
        automaticDeferredDeepLinks: false,
        onLink: (event) {
          if (event case LinkEvent(:final deepLink)) routeLink(deepLink);
        },
      );
      final link = await WarpLink.checkDeferredDeepLink();
      if (link != null && link.isDeferred) {
        routeLink(link);
      }
    } on WarpLinkException catch (error) {
      // Offline on first launch: the attempt is not consumed, so the SDK
      // retries on the next launch. Show the default experience now.
      debugPrint('Deferred deep link check failed: ${error.message}');
    } finally {
      if (mounted) {
        setState(() => _ready = true);
      }
    }
  }

  @override
  Widget build(BuildContext context) => Stack(
        fit: StackFit.expand,
        children: <Widget>[
          widget.child,
          if (!_ready)
            const ColoredBox(
              color: Colors.black,
              child: Center(child: CircularProgressIndicator()),
            ),
        ],
      );
}
```

Mount it around the navigator. The gate keeps the navigator mounted underneath the splash and draws the splash on top of it, so `navigatorKey.currentState` exists by the time the check resolves. A route pushed while the splash is up lands on the mounted navigator, and the splash lifts to reveal it. If the check resolves before the first frame, `routeLink` waits for that frame, as the routing section below shows:

```dart
// lib/gated_app.dart
import 'package:flutter/material.dart';

import 'deferred_navigation.dart';
import 'splash_gate.dart';

class GatedApp extends StatelessWidget {
  const GatedApp({super.key});

  @override
  Widget build(BuildContext context) => MaterialApp(
        navigatorKey: navigatorKey,
        builder: (context, navigator) => SplashGate(child: navigator!),
        routes: <String, WidgetBuilder>{
          '/': (context) => const Placeholder(), // your home screen
          '/product': (context) => const Placeholder(), // your product screen
          '/welcome': (context) => const Placeholder(), // your onboarding screen
        },
      );
}
```

Two properties of the check make this safe. It runs once per install: the native SDK caches the result once the check has definitively completed, and every later call returns that stored result with no network request, the same match if one was found and `null` if there was none. And an attempt that produced no usable answer, such as an offline first launch, is not recorded as complete, so it retries on the next launch instead of caching a permanent `null`.

The completion marker is install scoped on purpose. It is a backup excluded file in the app container on iOS and a file in `noBackupFilesDir` on Android, and no restore brings either back, so a reinstall attributes fresh. A separate device level marker outlives the uninstall (the Keychain on iOS, `SharedPreferences` on Android) and only tags the attribution request so a reinstall can be counted separately. Neither is readable from Dart.

## Routing the Match

Here is the part that catches people. A router configuration maps URLs to screens, and a deferred match is not a URL: it is an object arriving from a native SDK after the app has already launched. Route the object yourself, through a navigator key, because the callback can fire before the first frame. On the first launch after an install, it usually does.

```dart
// lib/deferred_navigation.dart
import 'package:flutter/widgets.dart';
import 'package:warplink_flutter/warplink_flutter.dart';

final navigatorKey = GlobalKey<NavigatorState>();

typedef LinkRoute = ({String name, Object? arguments});

/// The product id the link names, checked one source at a time. customParams
/// holds the destination URL's query on a tap, but a deferred match carries
/// none, so the in-app URL's query comes next and the destination's last.
String? productIdOf(WarpLinkDeepLink link) {
  final candidates = <Object?>[
    link.customParams['product_id'],
    Uri.tryParse(link.deepLinkUrl ?? '')?.queryParameters['product_id'],
    Uri.tryParse(link.destination)?.queryParameters['product_id'],
  ];
  for (final value in candidates) {
    if (value is String && value.isNotEmpty) return value;
  }
  return null;
}

/// Picks a screen from the match. Identity work needs a guarantee, not a high
/// score, and this function only chooses content.
LinkRoute chooseRoute(WarpLinkDeepLink link) {
  final product = productIdOf(link);
  final confidence = link.matchConfidence ?? 0;

  if (product != null && (link.matchGuaranteed || confidence > 0.5)) {
    return (name: '/product', arguments: product);
  }
  if (confidence > 0.3) {
    return (name: '/welcome', arguments: link.destination);
  }
  return (name: '/welcome', arguments: null);
}

void routeLink(WarpLinkDeepLink link) {
  final route = chooseRoute(link);

  void push() => navigatorKey.currentState
      ?.pushNamed(route.name, arguments: route.arguments);

  if (navigatorKey.currentState != null) {
    push();
    return;
  }
  // The navigator has not been built yet. Wait for the first frame.
  WidgetsBinding.instance.addPostFrameCallback((_) => push());
}
```

The `/welcome` screen receives the suggestion as a nullable string: the link's web destination when the match is soft, or `null` for a plain first-run experience. The product id comes from `productIdOf`. On a tap, `customParams` holds the query parameters of the link's destination URL, as a `Map<String, Object?>` of JSON values, so the `is String` test is the check. A deferred match carries no custom parameters, so the function checks the query of `deepLinkUrl`, the link's per-platform in-app URL, next and the query of `destination` last, and returns the first `product_id` it finds. A link without the parameter falls through to the softer branches instead of failing.

Three rules fall out of this code:

- **A guaranteed match can go straight to the content.** `matchGuaranteed` is `true` only for a deterministic match, so a product id on a guaranteed match is safe to open. Treat it as a reliable hint, not an identity.
- **A probabilistic match earns public content only above 0.5.** Below that, show a soft suggestion or the default first-run screen.
- **Below 0.3, ignore it.** Show your normal onboarding and let the attribution do its work in the background.

If your app uses `go_router`, the shape is the same. Create the router once, outside any widget, and call it from the same post-frame guard. Keep Flutter's own deep-linking flag off so the router has one source:

```dart
// lib/deferred_go_router.dart
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
import 'package:warplink_flutter/warplink_flutter.dart';

import 'deferred_navigation.dart' show productIdOf;

final rootNavigatorKey = GlobalKey<NavigatorState>();

final GoRouter router = GoRouter(
  navigatorKey: rootNavigatorKey,
  routes: <RouteBase>[
    GoRoute(path: '/', builder: (context, state) => const Placeholder()),
    GoRoute(
      path: '/product/:id',
      builder: (context, state) => Text('Product ${state.pathParameters['id']}'),
    ),
    GoRoute(
      path: '/welcome',
      builder: (context, state) => Text('Welcome ${state.extra ?? ''}'),
    ),
  ],
);

void routeWithGoRouter(WarpLinkDeepLink link) {
  final productId = productIdOf(link);
  final confidence = link.matchConfidence ?? 0;

  void go() {
    if (productId != null && (link.matchGuaranteed || confidence > 0.5)) {
      router.go('/product/$productId');
    } else {
      router.go('/welcome', extra: confidence > 0.3 ? link.destination : null);
    }
  }

  if (rootNavigatorKey.currentContext != null) {
    go();
    return;
  }
  // The first frame has not mounted the router yet.
  WidgetsBinding.instance.addPostFrameCallback((_) => go());
}
```

## Testing Deferred Deep Links on Each Platform

A deferred check fires once per install, on the genuine first launch, so test from a clean install.

**Both platforms, first.** Create a test link in the dashboard with a destination and, if you have one, an iOS and Android deep link URL. Turn on `debugLogging: true` in `configure()` so the native side traces what it did. Keep the gap between tapping the link and opening the installed app short, ideally inside an hour, both to stay inside the match window and to land in the top confidence band.

**A reinstall counts as an install.** The check is scoped to one install on both platforms, so deleting the app and installing it again runs it again. A hot restart, a rerun without uninstalling, or a new `flutter run` over the existing app is not a fresh install, and the check returns the stored result with no network request.

**iOS.** Install through TestFlight for the closest match to a store install. For an ordinary retest, delete the app and install it again with `flutter run`. For the first-install path rather than the reinstall path, erase the simulator (Device, then Erase All Content and Settings, or `xcrun simctl erase`) or use a device that has never run the app.

**Android.** Use an internal testing track install. That is the only route that produces a real Play Install Referrer, so it is the only way to test the deterministic path Android users actually get. A sideloaded build has no referrer and falls through to the probabilistic match. That is still a useful test, since it exercises the path iOS uses, but do not read it as proof the referrer branch works.

### First-Open Test, Step by Step

Run this once per platform. It keeps the test valid, because a deferred check only fires on a genuine first launch.

1. **Create the link.** In the dashboard, create a link with a destination and, if the screen needs it, a `product_id` query parameter on that destination or on the in-app URLs, for example `https://example.com/shop?product_id=42`. A deferred match carries no custom parameters, so the sample reads the value off those URLs.
2. **Build the right app.** Use `flutter run --release` on a device, or a TestFlight or internal testing build, with `debugLogging: true`.
3. **Start from a clean install.** Delete the app. A rerun or a hot restart does not reset the install marker.
4. **Tap the link on the test device,** from Notes or Messages, in Safari or Chrome. Do not paste it into the address bar.
5. **Install the app and open it within the hour,** on the same network you tapped from. Inside the first hour an iOS probabilistic match is capped at 0.85.
6. **Read the result.** The `onLink` event arrives with `isDeferred: true`. If it does not, run the checks below before you change any code.

```dart
// lib/attribution_state.dart
import 'package:flutter/foundation.dart';
import 'package:warplink_flutter/warplink_flutter.dart';

Future<void> logAttributionState() async {
  debugPrint('native SDK version: ${await WarpLink.sdkVersion()}'); // 1.2.0
  debugPrint('configured: ${await WarpLink.isConfigured()}');
  debugPrint('check complete: ${await WarpLink.isAttributionComplete()}');

  final result = await WarpLink.getAttributionResult();
  debugPrint(
    result == null
        ? 'attribution: no match'
        : 'attribution: ${result.linkId} ${result.matchType.name} '
            '${result.matchConfidence} guaranteed=${result.matchGuaranteed}',
  );
}
```

`isAttributionComplete()` returns `false` until the deferred check has definitively finished for this install. `getAttributionResult()` returns the stored result of that check without a new network call, and `null` means no match. Call `logAttributionState()` from a debug button, not at startup.

**What a good result looks like.** On Android through the Play track: `matchType` of `deterministic`, `matchConfidence` of 1.0, `matchGuaranteed` true. On iOS through TestFlight on a device that never had the app: `matchType` of `probabilistic`, `matchGuaranteed` false, and around 0.85 if you tested inside the hour. Get those two and the wiring is correct.

You can read the native logs while you test. On iOS, the Xcode console shows `[WarpLink] First launch: collecting device signals for attribution`, then either `Deferred deep link matched: <linkId>` or `No deferred deep link match`. On Android, run `adb logcat -s WarpLink` for the same lines.

## Match Behavior to Design Around

Deferred matching is deterministic where the platform gives it a referrer and confidence scored where it does not. Design your first screen around the score.

- **iOS first installs score up to 0.85 inside the first hour.** The match is probabilistic and `matchGuaranteed` is `false`.
- **Shared networks are scored for you.** WarpLink lowers the confidence when several devices share an address, and for carrier grade NAT.
- **Keep the network the same between tap and install.** Tap and install on the same Wi-Fi or mobile network so the click and the install share an IP address.
- **The match window is set per link.** The default is 6 hours, set per link, up to 24 hours.
- **Android installs through the Play Store referrer return a guaranteed match.** Other installs use the same probabilistic match as iOS.
- **Each match is delivered once.** A delivered link is never offered again, and `getAttributionResult()` returns the stored result.
- **A match chooses a screen.** Authenticate the user separately before you sign in, restore a session, or show personal data.

## Why Isn't It Firing?

Use this checklist when a first open does not route to your screen.

- **The navigator was not ready.** The deferred dispatch runs from `configure()`, which you called before the first frame. A bare `navigatorKey.currentState?.pushNamed(...)` does nothing when `currentState` is still `null`, so the app sits on the home screen. Wait for `addPostFrameCallback`, as in the routing section.
- **Configure the SDK with an SDK key.** Create it under Keys, SDK keys. An API key shares the `wl_live_` prefix and passes the format check, but only an SDK key records installs.
- **You tested by rerunning or hot restarting.** Neither is a fresh install. The completion marker survives both, so the check returns the stored result with no network request. Uninstall the app first.
- **Keep the tap and the install on one network.** The probabilistic match uses the request address on both sides.
- **You expected the launch link to carry it.** It never will. A deferred match does not travel as a URL, so it appears in neither `getInitialDeepLink()` nor your router's route table.
- **You got the same match twice.** That is the stored result at work. The manual `checkDeferredDeepLink()` always returns the stored result, while the automatic dispatch through `onLink` delivers a match at most once. Route from one or the other.
- **The iOS build fails to find the package.** Flutter 3.38 to 3.43 need `flutter config --enable-swift-package-manager`, then `flutter clean` and a rebuild.

If the link fires but the app opens a browser instead of your screen, that is Universal Link or App Link routing rather than deferred matching, and it is diagnosed against the association files. Our [deep link checker](https://warplink.app/tools/deep-link-checker) reads both files for a domain.

## Frequently Asked Questions

**Does deferred deep linking in Flutter need native code?**
No. The plugin wraps the native iOS and Android SDKs, registers itself with Flutter's life cycles, and starts the deferred check from `configure()`. You add an Associated Domains entry on iOS, an intent filter on Android, and set `minSdk` to 26. Those serve tapped links. The deferred check itself runs from `configure()` straight to the attribution endpoint.

**Do I need to call checkDeferredDeepLink myself in Flutter?**
No. `configure()` fires the check automatically and delivers a match through `onLink` with `isDeferred` set to true. Call `checkDeferredDeepLink()` yourself only when you set `automaticDeferredDeepLinks: false`, or when you want to hold a splash until the result is known. Omitting `onLink` does not switch the check off, because that request is what attributes the install.

**Why does nothing happen on the first launch after install?**
The usual causes are a navigator that did not exist yet when the callback fired, an API key used where an SDK key was required, a rerun that was not a fresh install, and a store gap longer than the match window. Wait for the first frame before you navigate, check that the key came from Keys then SDK keys in the dashboard, uninstall the app before each test, and keep the click to install gap short.

**Why is Android deferred matching more accurate than iOS?**
The Play Store passes the click referrer through the install, so Android gets a deterministic match with confidence 1.0 and `matchGuaranteed` true. The App Store passes nothing equivalent, so a genuine first install on iOS is matched by a probabilistic match that decays from 0.85 inside the first hour. The same Dart handles both, but the confidence you get back differs by platform.

**How do I test Flutter deferred deep links without publishing to the stores?**
Uninstall the app, tap the link in the device browser, then install again with `flutter run` and open it. That exercises the probabilistic path, which is the path iOS uses. To exercise the real Play Install Referrer on Android, install through an internal testing track, because a sideloaded build has no referrer. On iOS, TestFlight is the closest match to a store install.

**Does deferred deep linking need the IDFA or an App Tracking Transparency prompt?**
No. The iOS side uses the IDFV, which is vendor scoped and exempt from App Tracking Transparency, plus a match key the server computes from the request. The SDK never touches the IDFA or the Google Advertising ID, so it adds no permission dialog to your first launch on either platform.

## Sources

- Flutter, [Deep linking](https://docs.flutter.dev/ui/navigation/deep-linking): the framework's own handler, which reports only a URL the OS delivered, which is why a fresh install has nothing to report.
- Android Developers, [Play Install Referrer](https://developer.android.com/google/play/installreferrer): the referrer the Play Store carries through an install.
- Apple, [identifierForVendor](https://developer.apple.com/documentation/uikit/uidevice/identifierforvendor): the vendor-scoped identifier the iOS side uses instead of the IDFA.
- Flutter, [addPostFrameCallback](https://api.flutter.dev/flutter/scheduler/SchedulerBinding/addPostFrameCallback.html): the callback used to wait for the first frame before navigating.
- Flutter, [Swift Package Manager for app developers](https://docs.flutter.dev/packages-and-plugins/swift-package-manager/for-app-developers): how to turn on Swift Package Manager for the iOS side of a plugin.

## Related Guides

- **Each platform in depth:** [Deferred Deep Linking on iOS](https://warplink.app/blog/deferred-deep-linking-ios) and [Deferred Deep Linking on Android](https://warplink.app/blog/deferred-deep-linking-android) go further into the IDFV, Private Relay, and the Play Install Referrer than a cross platform post can.
- **Invite and referral links:** [Referrals](https://warplink.app/docs/guides/referrals) covers `redeemInvitation`, `claimReferral`, and the signed webhook.
- **The setup underneath this one:** [Flutter Deep Linking](https://warplink.app/blog/flutter-deep-linking) covers the entitlement, the intent filter, Flutter's own deep-linking flag, and go_router wiring for tapped links.
- **Start here for the concepts:** [What Is Deep Linking? How Mobile Deep Links Work on iOS and Android](https://warplink.app/blog/deep-linking-guide).
- **When a tapped link misbehaves:** [Universal Links Not Opening?](https://warplink.app/blog/universal-links-not-opening) for iOS, and [Android App Links autoVerify Failed](https://warplink.app/blog/android-app-links-autoverify-failed) for the Android association file.
- **The same guide for another framework:** [Deferred Deep Linking in React Native](https://warplink.app/blog/deferred-deep-linking-react-native) covers the same match cascade from TypeScript.
- **The short version of the mechanism:** [deferred deep linking](https://warplink.app/deferred-deep-linking), with iOS and Android side by side in one table.
- **Reference:** the [Flutter deferred deep links docs](https://warplink.app/docs/sdks/flutter/deferred), the [SDK setup guide](https://warplink.app/docs/sdks/flutter), the [attribution docs](https://warplink.app/docs/sdks/flutter/attribution), and the [deferred deep links concept page](https://warplink.app/docs/concepts/deferred-deep-links).
- **Choosing an SDK:** [5 Deferred Deep Linking SDKs Compared](https://warplink.app/blog/deferred-deep-linking-sdks-compared) sets the vendors' first-open matching, platform coverage, and published pricing side by side.

## How WarpLink Helps

Everything above is the mechanism, and the mechanism does not change depending on who runs it. What a service has to provide are the two halves you cannot host inside your app: the click recorder at the edge that captures signals before the store takes over, and the attribution endpoint that computes the match key from the request IP and walks the match cascade. WarpLink's Flutter SDK is the bridge between those and your Dart, and it collapses to `WarpLink.configure(apiKey:, onLink:)`, one callback, and an `isDeferred` check. It is MIT licensed with no third party runtime dependencies, and it wraps the same native iOS and Android SDKs that native apps use, so attribution in a Flutter app behaves exactly as it does in a native one.

The part worth saying plainly is that deferred deep linking is install attribution. The same match that routes the user also tells you which link, which campaign, and which share drove the install, because `linkId`, `deepLinkUrl`, `matchType`, `matchConfidence`, and `matchGuaranteed` come back in the same payload. Route the user and attribute the install in one call. That is the bridge from the linking pillar to the attribution pillar, and from there to the real time analytics that show which taps became users, on iOS and Android, from one codebase.

[Create a free WarpLink account](https://dash.warplink.app/auth/signup) and get deep linking, install attribution, and analytics in one SDK, with 10,000 clicks a month on the free tier and no time limit. The [Flutter SDK docs](https://warplink.app/docs/sdks/flutter) have the full setup.
