Deferred Deep Links in Flutter: From Cold Start to the Right Screen
A deep link is a URL that opens a specific screen of your app instead of its home screen. A deferred deep link does the same for someone who does not have the app yet: the tap goes to the store, and the destination is delivered after the install, on the first launch.
This guide covers where link data arrives in a Flutter app's life, and how to act on it once, after onboarding or login. The code uses flutter_adto, AdTo's Flutter SDK.
Three ways a link reaches a Flutter app
| Path | State of the app | Where the link arrives |
|---|---|---|
| Cold start | Installed but not running. The tap launches it. | onLinkClick emits once, and getInitialLink() returns the same object |
| While running | In the foreground or the background | onLinkClick |
| Deferred | Not installed. The tap goes to the store. | onAppInstalled, on the first launch after the install |
In the third row nothing arrives as a URL. On the first launch the SDK registers the install with AdTo, and the server answers with a verdict: whether an AdTo link brought this install, and which one. That answer can land seconds after the first frame, when the new user is already in your onboarding.
Platform setup in brief
To open the installed app straight from a tap, iOS needs Universal Links and Android needs App Links. Both depend on a file served from the link's domain. AdTo links live at https://<username>.adto.app/<slug>, and AdTo serves both files for that host from the app record in the dashboard. In the app you add:
- iOS. The Associated Domains entitlement in
ios/Runner/Runner.entitlements, with the entryapplinks:<username>.adto.app. - Android. An
httpsintent filter withandroid:autoVerify="true"andandroid:host="<username>.adto.app"on the launcher activity. - Optional. A custom URL scheme such as
myapp, saved in the app record and registered on both platforms.
The file formats are explained in the AASA file guide and the assetlinks.json guide, and the exact entries are on the Platform setup page.
flutter_adto receives links through the app_links plugin. Flutter also has a deep link handler of its own, which hands an incoming URL to your Navigator or Router as a route, and since Flutter 3.27 it is on by default. Flutter's App Links cookbook says the default handler breaks third-party plugins such as app_links, and tells you to opt out. On Android, inside the <activity>:
<meta-data android:name="flutter_deeplinking_enabled" android:value="false" />
On iOS, Flutter says to add the key FlutterDeepLinkingEnabled to Info.plist, set to false:
<key>FlutterDeepLinkingEnabled</key>
<false/>
Install and initialize the SDK
The package is flutter_adto on pub.dev, version 1.0.0. It needs Flutter 3.29, Dart 3.7, iOS 15.0 and Android 7.0 (API 24), or newer.
flutter pub add flutter_adto
Initialize it once with an SDK key, which starts with adto_pub_ and comes from the dashboard's Settings page. Pass it at build time with --dart-define=ADTO_API_KEY=adto_pub_…. Subscribe to both streams before you call initialize, and do not hold the first frame for it.
import 'dart:async';
import 'package:flutter/material.dart';
import 'package:flutter_adto/flutter_adto.dart';
final adto = FlutterAdto();
Future<void> startAdto() async {
adto.onLinkClick.listen(onLink);
adto.onAppInstalled.listen(onInstall);
try {
await adto.initialize(const AdtoConfig(
apiKey: String.fromEnvironment('ADTO_API_KEY'),
));
} on AdtoError catch (e) {
debugPrint('AdTo did not start: $e');
}
}
void main() {
WidgetsFlutterBinding.ensureInitialized();
unawaited(startAdto());
runApp(const MyApp());
}
On a first launch, initialize returns only after the install registration has finished. That includes the wait for the Android install referrer, 5 seconds at most by default, and on iPhone a pasteboard read of up to 6 seconds when the user has to answer the paste alert. Awaiting it before runApp would hold the first frame that long.
Handle links that open the app
onLinkClick is a broadcast stream of AdtoLinkClick. getInitialLink() returns the link that launched the app, or null. On a cold start the two deliver the same object, so feed only one into your handler. The listener above is attached before initialize, so the stream is enough.
void onLink(AdtoLinkClick click) {
if (click.error != null) return; // not an AdTo link
final route = click.clickParams?.deepLink // adto_deeplink on the URL
?? click.linkResolution?.deepLinkPath; // the link's saved route
if (route != null) pending.fromLink(route);
}
If both are empty, map click.slug to a screen. On a custom-scheme open, a link's route (saved or per-tap) is the URL's own host and path, in click.originalUrl. The SDK processes the cold-start link once per process and treats the same URL delivered twice within 10 seconds as one open.
Handle the deferred link after an install
onAppInstalled delivers the verdict as an AdtoAppInstallResponse. Two fields answer different questions.
matchedis attribution credit. The server grants it only atguaranteedconfidence, where a signal such as a store referrer or a copied link named the click, or athigh.routingis the candidate for deferred routing. It is also present atmediumconfidence, wherematchedisfalse: enough to show the new user what they tapped, not enough to credit anyone.
void onInstall(AdtoAppInstallResponse install) {
final route = install.routing?.deepLink ?? install.deepLink;
if (route != null) pending.fromInstall(route);
if (install.matched) {
// credit install.slug
}
}
Three behaviours of this stream shape the routing code:
- It replays. A listener that subscribes late still receives the latest verdict.
- It can emit more than once. A late signal, such as a store referrer delivered after the first launch, upgrades the verdict, and the stream emits again.
- It belongs to the first launch. Later launches never register again, and emit nothing unless a late signal upgrades the verdict.
The route comes from the tapped URL: https://acme.adto.app/welcome?adto_deeplink=products/42 comes back as products/42. A browser tap stores only its adto_* and utm_* values, so a parameter of your own such as ?productId=42 does not survive the trip through the store (see URL parameters). A path saved on the link is not on the verdict either: read it with resolveLink(username, slug) and deepLinkPath.
On iPhone, with iOS tap-to-store on for the app, the tap lands on a page whose Get button (Get plus your app's name) copies the link with its click id and opens the App Store. The SDK reads the pasteboard once at first launch. Apple documents that in iOS 16 and later a programmatic paste raises an approval alert, and willShowPasteboardPrompt() tells you whether this launch will show one.
Route once: hold the destination until onboarding or login is done
Neither handler navigates. Each offers a route to one object that knows whether the user may go there yet:
class PendingDestination {
PendingDestination(this.open);
final void Function(String route) open;
String? _route;
bool _ready = false; // onboarding and login are done
bool _linkOpened = false; // in this process
bool _deferredUsed = false; // persist this one
void fromLink(String raw) {
_linkOpened = true;
_hold(raw);
}
void fromInstall(String raw) {
final first = !_deferredUsed;
_deferredUsed = true;
if (first && !_linkOpened) _hold(raw);
}
void setReady(bool ready) {
_ready = ready;
_flush();
}
void _hold(String raw) {
// 'myapp://products/42' and '/products/42' become 'products/42'
final i = raw.indexOf('://');
final route = i < 0 ? raw : raw.substring(i + 3);
_route = route.startsWith('/') ? route.substring(1) : route;
_flush();
}
void _flush() {
final route = _route;
if (!_ready || route == null) return;
_route = null;
open(route);
}
}
final pending = PendingDestination(openRoute); // your navigation
Call pending.setReady(true) when onboarding is finished and the user is signed in, and setReady(false) when they sign out. The class also encodes three rules:
- A link that opened the app beats the deferred route.
- Only the first verdict that carries a route is used, so an upgraded verdict never moves the user twice.
- Routes are normalised in one place: a verdict's route has no scheme, while an opened URL carries the raw
adto_deeplinkvalue.
The state is in memory, so a user who quits during email verification loses the destination: later launches do not emit the verdict again. Save the held route and the _deferredUsed flag in your own storage and restore them at startup.
Test on a simulator, an emulator and a device
Give debug builds the SDK key of your test environment, a second account named t-<username> that keeps test installs out of the live numbers, and add its host, t-<username>.adto.app, to their entitlement and intent filter. Create a link there with a deep link path, for example welcome with the path products/42, then fire it at the app through your registered custom scheme:
# Android emulator
adb shell am start -a android.intent.action.VIEW -d "myapp://products/42?adto_l=t-acme/welcome"
# iOS simulator
xcrun simctl openurl booted "myapp://products/42?adto_l=t-acme/welcome"
The host and path are your app's own route, and adto_l names the link. Run it with the app killed (cold start), in the background, and in the foreground, more than 10 seconds apart. Each time onLinkClick should emit once. Repeat signed out: the screen should open only after login.
As Flutter's cookbook notes, an adb launch tests the app side only. To test the https link itself, tap it from another app on a real device. If the browser opens instead, see this checklist.
The deferred path needs a physical device and a build installed from the store: one installed with flutter run has no campaign referrer.
- Save the real store URLs and the installed build's signing fingerprint in the app record. For iPhone, turn on iOS tap-to-store.
- Uninstall the app, tap a live link with
?adto_deeplink=products/42on the device, install from the store and open the app once. - Expect a verdict with
matched: trueandmatchConfidence: 'guaranteed'(on iPhone, only if you allow the paste), and the destination only after onboarding.
Each test consumes its click, so tap again for every run.
Mistakes to avoid
- Routing only when
matchedis true.routinglets a medium-confidence candidate still open the right screen. - Carrying the destination in your own query parameter. Put it in
adto_deeplink. - Sending an AdTo link tapped inside your own app to the browser. Pass it to
handleUrl(url).
Doing this with AdTo
AdTo is a hosted service for short links, deferred deep links and install attribution. Your links live at https://<username>.adto.app/<slug>, and AdTo serves the Universal Links and App Links files for that host.
flutter_adto delivers opened links on onLinkClick and the install verdict on onAppInstalled. On Android the SDK reads the Play Install Referrer on first launch, and on iPhone the link that the tap-to-store page copied. Otherwise the server falls back to a fingerprint, a scored comparison of the tap and the first launch, and credits only a unique, high-confidence match. AdTo is not a measurement partner (MMP): it has no SKAdNetwork support and sends no postbacks to ad networks.
Create an AdTo account to try it. The verdict's fields are on the Install attribution page, and the full test list is on the Testing page.