Test deep links in Flutter

After this page, you've seen each kind of link open your Flutter app on a real phone, and you know where to look when one doesn't.

On this page 7
  1. 1. Test the routing without a tap
  2. 2. Tap a real link from a chat app
  3. 3. Ask what a tap would do
  4. 4. Test a deferred link from Google Play
  5. 5. Check reports and re-run the deferred check
  6. Common errors
  7. Next steps
Time
About 15 minutes, plus a Google Play internal testing build for deferred links
You need
Links routed to screens (Receive links), an Android phone with USB debugging
Works on
Android, iPhone

1. Test the routing without a tap

Terminal
# Browser hand-off (custom scheme)
adb shell am start -W -a android.intent.action.VIEW -d "yourapp://shop.example.com/product/42?color=red"

# Verified link (needs App Links verified: go-live checklist, step 2)
adb shell am start -W -a android.intent.action.VIEW -d "https://hilltop.strait.link/summer"

You should see: the Product screen for 42 with color red, once with the app closed and once from the background.

Send https://hilltop.strait.link/summer to yourself in Google Messages, Gmail and WhatsApp, and tap it in each. Pasting into the address bar never opens an app.

You should see: the app opens on the link's screen. WhatsApp and Instagram may show an Open in app page first, because in-app browsers often don't open apps on their own.

3. Ask what a tap would do

Terminal
curl "https://strait.link/v1/simulate?url=https%3A%2F%2Fhilltop.strait.link%2Fsummer&ua=instagram-android" \
  -H "Authorization: Bearer $SECRET_KEY"

You should see: a decision, the location the phone would go to, and a plain-English reason. No tap is recorded. See Dry-run a tap.

The link travels through the Google Play Install Referrer, so install from Google Play internal testing (go-live checklist, step 3). Then uninstall, tap the link, install from Play and open the app.

You should see: the first screen is the link's screen, and the console logs Strait link: deferred install_referrer true /product/42. Uninstall again to repeat: the check runs once per install.

5. Check reports and re-run the deferred check

Dart
debugPrint('waiting to send: ${await links.pendingOpenReports()}');
await links.flushOpenReports();
final e = await links.checkDeferred();   // never records an install
debugPrint('${e.kind.name} ${e.matched} ${e.reason} ${e.path}');

You should see: waiting to send: 0 when the phone is online.

Common errors

  • The deferred test opens the home screen. The build came from flutter run, not Play, or "When someone without the app taps a link" isn't Always Google Play while the app is unlisted.
  • Verified link opens the browser. The installed build's certificate isn't in Apps & stores (go-live checklist, step 1).
  • iPhone installs don't match. Check the time zone is an IANA name. More in Troubleshooting.

Next steps