Deferred links

A deferred deep link is a link someone tapped before your app was installed. They go to the store, install, open the app, and should land on the screen the link was for instead of the home screen.

Lander does this wherever it can be done honestly, and labels every result with a confidence and a method. This page covers the app side. For the background (why iOS is harder, what is stored, privacy) read Deferred deep linking.

At a glanceCopy Anchor Link

Handle them in your appCopy Anchor Link

Deferred links arrive like every other link: on Lander.onDeepLink, or from Lander.getInitialLink(), exactly once. isDeferred is true. The one exception is claimHandoff, which returns its link to you directly.

Lander.onDeepLink.listen((link) {
  if (link.isDeferred && link.confidence == LanderConfidence.probabilistic) {
    // A good guess: show the screen, but do not act on it as if the user
    // had tapped it in the app.
  }
  router.go(link.route, extra: link);
});

Rules the SDK follows for you:

• Only a first launch can produce a deferred link (from the store, or after a reinstall, since the install ID does not survive an uninstall).
• If the first launch was itself opened by a link, that link wins and no deferred link is delivered on top of it.
• On a first launch without a link, getInitialLink() waits for the launch report so it can return the deferred link. On later launches it returns null immediately.

Android: install referrerCopy Anchor Link

When someone without your app taps a Lander link on Android, Lander sends them to your Play Store listing with a short, single use token in the Play Store's install referrer. On first launch the SDK reads the Play Install Referrer once and sends it to Lander, which turns it back into the link.

Your app receives it with isDeferred: true, confidence: deterministic and method: install_referrer. There is nothing to code.

It does not work when:

• The app was not installed from Google Play (another store, a sideloaded APK, flutter run, an emulator without Play).
• The install happened more than 7 days after the click (tokens expire) or the token was already used.
• The link has an Android fallback URL. That URL wins, and Lander cannot add a token to a page it does not control.

iOS: Continue in app pageCopy Anchor Link

Apple gives apps no install referrer, so Lander offers a small page instead of an immediate App Store redirect. It shows your app and two buttons: Get the app on the App Store and I already have the app, open it. After installing, the person comes back to the page (it stays open in Safari) and taps the second button.

The app opens through that button, so the link arrives as an ordinary open on the stream, with confidence: deterministic, method: landing_page, and isDeferred: true when the app was installed after the click.

To use it:

1. Set the App Store ID of your iOS app in Build > Platforms. The page needs it.
2. Add a custom URL scheme to your app and enter it as the URI scheme of the iOS app. iOS keeps a Universal Link tapped on a page of its own domain inside Safari, so without a scheme the button may reload the page instead of opening your app. With a scheme the button opens acmeshop://<path>?lander_link=<short link>, and the SDK resolves the short link inside it.
3. Turn on iosLandingPage for the project. There is no dashboard switch yet, so use the API with a secret key:

curl -X PATCH https://api.golander.link/v1/deferred/settings \
  -H "Authorization: Bearer sk_live_..." \
  -H 'Content-Type: application/json' \
  -d '{"iosLandingPage": true}'

Links with an iOS fallback URL skip the page and go to that URL.

Authenticated handoffCopy Anchor Link

If people sign in to your app, your own account system is the most reliable bridge, on both platforms. Typical case: someone taps an invite on their laptop, signs up on your website, then installs the app on their phone.

1. Your server binds a link to the user, with a secret key:

curl https://api.golander.link/v1/handoffs \
  -H "Authorization: Bearer sk_live_..." \
  -H 'Content-Type: application/json' \
  -d '{"userId":"8f2c41d0-...","url":"https://acme.golander.link/invite-42"}'

Instead of url you can send a linkId, or the lander_token of the exact click as token. A handoff expires after 7 days unless you pass a shorter expiresIn (in seconds).

2. The app claims it right after that user signs in:

final user = await auth.signIn();

try {
  final link = await Lander.claimHandoff(user.id); // null when nothing is pending
  if (link != null) router.go(link.route, extra: link);
} on LanderException catch (e) {
  // Offline, rate limited, or the install is not registered yet.
  debugPrint('Handoff claim failed: ${e.code}');
}

static Future<LanderLink?> claimHandoff(String userId)

What to know:

• The link comes back with isDeferred: true, confidence: deterministic and method: authenticated_handoff.
• It is returned only, never also emitted on onDeepLink, so navigate with it yourself.
• The newest pending handoff wins, and claiming clears every pending handoff for that user. A second call returns null.
• If the handoff was made before the app was installed, the install is attributed to the link too.
• Retries reuse one Idempotency-Key, so a lost response does not lose the link.
• userId is trimmed and must be 1 to 256 characters, otherwise claimHandoff throws an ArgumentError. Lander stores only a salted hash of it.
• It throws a LanderException when the request fails after retries, when the API rate limits it (10 claims per install per minute), or with code install_not_registered when the SDK could not report this install to Lander yet (for example, offline since the first launch).

iOS: probabilistic matchingCopy Anchor Link

Off by default. When a project turns on probabilisticMatching, Lander keeps a few coarse facts about recent iPhone clicks (iOS major version, country, time). On an iOS first launch, if every recent click with the same iOS version and country points at the same link, the app gets it with confidence: probabilistic and method: probabilistic_match. Turning on probabilisticIpMatching as well matches clicks from the same network first, which finds far more installs.

The SDK sends nothing extra for this: only the OS version it always reports. Treat the result as a suggestion. Land on a product or content screen; never sign someone in, apply a referral credit or reveal anything private because of it.

SettingsCopy Anchor Link

Per project, shared by the test and live environments. Change them with PATCH /v1/deferred/settings and a secret key; changes apply to the next click.

Check your privacy policy and App Store privacy details before turning on the probabilistic options. See Privacy.

Unattributed installsCopy Anchor Link

Every first launch that no flow could tie to a click is recorded as an unattributed install. Nothing is delivered and the app starts normally. That is not an error. If a deterministic link turns up later for that install (the Continue in app page, or a handoff claim), the install is upgraded to it.

Next stepsCopy Anchor Link