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.
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
onLinkcallback, andmatchGuaranteedtells 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, and for how it differs from a standard link, see 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.
flutter pub add warplink_flutter
// 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 and the referrals guide.
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:
- Run
flutter pub add warplink_flutter, and setminSdkto 26 on Android. - Create an SDK key under Keys > SDK keys in the dashboard.
- Call
WarpLink.configure(apiKey: ..., onLink: ...)once at startup. onLinkreceives aWarpLinkEvent. On aLinkEvent, route ondeepLink.isDeferred,matchType, andmatchConfidence.
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.
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:
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:
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:
// 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:
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 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:
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.
// 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:
// 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.
// 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.
matchGuaranteedistrueonly 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:
// 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.
- Create the link. In the dashboard, create a link with a destination and, if the screen needs it, a
product_idquery parameter on that destination or on the in-app URLs, for examplehttps://example.com/shop?product_id=42. A deferred match carries no custom parameters, so the sample reads the value off those URLs. - Build the right app. Use
flutter run --releaseon a device, or a TestFlight or internal testing build, withdebugLogging: true. - Start from a clean install. Delete the app. A rerun or a hot restart does not reset the install marker.
- Tap the link on the test device, from Notes or Messages, in Safari or Chrome. Do not paste it into the address bar.
- 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.
- Read the result. The
onLinkevent arrives withisDeferred: true. If it does not, run the checks below before you change any code.
// 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
matchGuaranteedisfalse. - 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 barenavigatorKey.currentState?.pushNamed(...)does nothing whencurrentStateis stillnull, so the app sits on the home screen. Wait foraddPostFrameCallback, 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 throughonLinkdelivers 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, thenflutter cleanand 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 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: 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: the referrer the Play Store carries through an install.
- Apple, identifierForVendor: the vendor-scoped identifier the iOS side uses instead of the IDFA.
- Flutter, addPostFrameCallback: the callback used to wait for the first frame before navigating.
- Flutter, 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 and Deferred Deep Linking on Android go further into the IDFV, Private Relay, and the Play Install Referrer than a cross platform post can.
- Invite and referral links: Referrals covers
redeemInvitation,claimReferral, and the signed webhook. - The setup underneath this one: 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.
- When a tapped link misbehaves: Universal Links Not Opening? for iOS, and Android App Links autoVerify Failed for the Android association file.
- The same guide for another framework: Deferred Deep Linking in React Native covers the same match cascade from TypeScript.
- The short version of the mechanism: deferred deep linking, with iOS and Android side by side in one table.
- Reference: the Flutter deferred deep links docs, the SDK setup guide, the attribution docs, and the deferred deep links concept page.
- Choosing an SDK: 5 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 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 have the full setup.
Get your first deep link working today
Deep linking, install attribution, and real-time analytics in one SDK. Free for 10K clicks a month, no sales call.
Stuck on setup? Email support@warplink.app and we will help you get one real link working.
WarpLink Team
Building affordable, reliable link infrastructure for mobile teams. Deep linking, install attribution, and real-time analytics in one SDK.
Related Posts
8 Best Flutter Deep Linking Packages in 2026
Eight Flutter deep linking packages for 2026, compared on pub.dev status, price, deferred deep links, and attribution, from go_router to hosted SDKs.
10 Deep Linking Mistakes That Break Install Attribution
Installs showing as unattributed? Ten deep linking mistakes that stop an install from matching its link, each with the symptom, the check, and the fix.
Flutter Deep Linking: Universal Links, App Links and Cold Start Setup
Flutter deep linking in nine steps: Associated Domains, an autoVerify intent filter, Flutter's link flag off, and a cold start that waits for the navigator.