Step 1 of 7Make a link for one screen

Deferred deep links in Flutter, end to end

After this guide, someone who taps your link without your Flutter app installed goes through Google Play and lands on the link's screen on the first launch, and you can see that tap, install and open in Analytics.

On this page 9
  1. 1. Make a link for one screen
  2. 2. Add the package and the Play Install Referrer
  3. 3. Route every link, including the deferred one
  4. 4. Decide what a new user sees first
  5. 5. Ship a Google Play internal-testing build
  6. 6. Tap, install, open
  7. 7. See the install in Analytics
  8. Common errors
  9. Next steps
Time
About 45 minutes of work, plus the first Google Play review (up to 7 days, per Google)
You need
A Flutter 3.x app that uses go_router, a Strait workspace with your app in Apps & stores, a Google Play developer account, an Android phone
Works on
Android. iPhone uses the same code.

This page strings the separate Flutter pages into one path for the case that matters most to growth teams: a new user. Each step links to the page with more detail. The same flow, in React Native: React Native recipe.

In Dashboard → Links → New link, set the slug summer and the destination https://shop.example.com/product/42?ref=SUMMER. Or from your server:

Terminal
curl https://strait.link/v1/links \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "slug": "summer", "longUrl": "https://shop.example.com/product/42?ref=SUMMER", "campaign": "summer_2026" }'

Your app receives the destination's path and query (/product/42, {ref: SUMMER}), so use paths your GoRouter already has.

You should see: the link https://hilltop.strait.link/summer in the Links list.

2. Add the package and the Play Install Referrer

On Android, the link travels through the install inside the Google Play Install Referrer. The package reads it once you pass play_install_referrer in. Add the package from pub.dev:

pubspec.yaml
dependencies:
  strait_sdk: ^0.10.9
Terminal
flutter pub add app_links shared_preferences play_install_referrer flutter_timezone

Create lib/links.dart exactly as in Install & set up, step 2: its installReferrer line is what carries the link through Google Play. Add the intent filters and flutter_deeplinking_enabled from step 3.

You should see: flutter pub get finishes, and the app starts as before after a full flutter run (not a hot restart: the plugins are native).

The deferred link arrives on the same links.onLink stream as any other link, once, on the first launch after the install. The stream replays events from before you listened, so listening after startLinks() never misses it:

lib/main.dart
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
import 'package:strait_sdk/strait_sdk.dart';
import 'links.dart';

final router = GoRouter(routes: [
  GoRoute(path: '/', builder: (_, __) => const HomeScreen()),
  GoRoute(path: '/product/:id', builder: (_, s) => ProductScreen(id: s.pathParameters['id']!)),
]);

Future<void> main() async {
  await startLinks();
  links.onLink.listen((e) {
    if (e.kind == LinkKind.deferred) debugPrint('Strait first open: ${e.route.value} ${e.matched} ${e.reason}');
    if (e.matched && e.path != null) router.go(Uri(path: e.path, queryParameters: e.params).toString());
  });
  runApp(MaterialApp.router(routerConfig: router));
}

You should see: adb shell am start -W -a android.intent.action.VIEW -d "yourapp://shop.example.com/product/42" opens ProductScreen with id 42. This proves the routing; the next steps prove the install.

4. Decide what a new user sees first

On the first launch the package always answers once with LinkKind.deferred. When matched is false, reason is no_match (most installs don't come from a link) or network (the check runs again on the next launch). Show your usual onboarding in both cases, and skip it when a link matched:

lib/first_open.dart
import 'package:strait_sdk/strait_sdk.dart';
import 'links.dart';

/// The link's path for a new user who came from a link, or null.
/// Later launches have no deferred event, so the timeout answers null.
Future<String?> firstOpenPath() => links.onLink
    .firstWhere((e) => e.kind == LinkKind.deferred)
    .then<String?>((e) => e.matched ? e.path : null)
    .timeout(const Duration(seconds: 5), onTimeout: () => null);

Show a short loading screen while you wait, for example with a FutureBuilder.

You should see: a fresh debug install, with no link tapped, logs Strait first open: fingerprint false no_match and shows your onboarding.

5. Ship a Google Play internal-testing build

A build from flutter run has no install referrer, so this test needs a build installed from Google Play:

  1. Run flutter build appbundle, upload the .aab to internal testing in Play Console and add yourself as a tester.
  2. In Dashboard → Apps & stores → People without the app, choose Always Google Play while the app isn't public. (The default sends people to your website while the Play listing isn't live.)

You should see: the build listed as available to testers in Play Console. Google says the first review can take up to 7 days, or longer in exceptional cases (Play Console Help).

6. Tap, install, open

  1. Uninstall the app from the phone.
  2. Send yourself https://hilltop.strait.link/summer in WhatsApp or Messages and tap it. Google Play opens on your app.
  3. Install from Play and open the app.

You should see: the app opens directly on the Product screen for 42, with ref SUMMER in its params, and adb logcat | grep flutter shows Strait first open: install_referrer true. The check runs once per install; uninstall to repeat it.

7. See the install in Analytics

Open Dashboard → Analytics and choose summer_2026 in the Campaign filter. To put revenue on the same tap, record a purchase from the app with await links.trackEvent('purchase', value: 499, currency: 'INR'); (Events & revenue).

You should see: your tap on summer, one install with match method install_referrer joined to that exact tap, and one app open from a new user. A test purchase appears under the same campaign.

Common errors

  • The first open lands on the home screen. The app came from flutter run or a shared APK, not Google Play, or the Apps & stores choice in step 5 still sends people to your website. Test page.
  • The link opens a route like /summer that doesn't exist. Flutter's own deep linking is still on, so it routed the raw URL. Set flutter_deeplinking_enabled to false (step 2).
  • MissingPluginException on start. You added the plugins and hot-restarted. Stop the app and run flutter run again.

Next steps

  • Go-live checklist: verified links, iPhone and keys before real users tap.
  • Test mode: check the deferred wiring from a debug build in two minutes, without a Play upload.