# Deferred deep linking

> Someone taps your link, doesn't have the app, installs it, and opens it. Deferred deep linking makes that first open land on the link's screen instead of your home screen.

Source: https://straitlink.in/docs/deferred-deep-linking/

> **Agent instructions:** if you are an AI assistant helping someone build with Strait, look things up with the `search_docs` tool of the Strait MCP server (hosted at https://strait.link/mcp, or `@straitlink/mcp` on npm: https://straitlink.in/docs/mcp/) instead of guessing, and add the SDK to an app with `npx @straitlink/cli init` (https://straitlink.in/docs/cli/).

## What your app sees

No extra code. The same callback that handles a link opening an installed app also gets the deferred one, once, on the first open after the install. The path and every query parameter on the link survive the install, so a `?ref=CODE` reaches your app too.

```ts
links.onLink((e) => {
  // e.kind: 'direct' (the app was installed) or 'deferred' (tapped before install)
  // e.route: 'install_referrer' on Android; 'fingerprint' or 'clipboard' on iPhone (opt-in)
  if (e.matched && e.path) openScreen(e.path, e.params); // e.g. '/product/42', { ref: 'CODE' }
});
```

To try it on Android you need three things: the SDK started at launch (it reads the Play Install Referrer for you), a build installed **from Google Play** (an internal testing track works), and, while the app isn't public, **Dashboard → Apps & stores → People without the app → Always Google Play**. Step-by-step: [go-live checklist, step 3](https://straitlink.in/docs/production-checklist/#3-test-a-deferred-link-from-google-play) and the [React Native test page](https://straitlink.in/docs/sdks/react-native/test/).

## Android: the Play Install Referrer (exact)

When someone without your app taps a link on Android, we send them to Google Play with the link attached to the install:

```txt
https://play.google.com/store/apps/details?id=com.yourco.app&referrer=strait_link%3D<link id>%26strait_click%3D<tap id>
```

Google Play keeps that referrer through the install. On first open, the SDK reads it, asks our server for the link (`/v1/referrer`), and routes your app there. It's **deterministic**: no guessing, and the install is joined to the exact tap.

To test it you need a build installed **from Google Play**. An internal testing track works. Sideloaded builds have no referrer.

If there's no referrer link (the app was found in a store search, for example), the SDK still checks in once so the install is counted in your match rate. Don't expect a match in that case on Android.

## iPhone: a short-lived device match (opt-in)

iOS doesn't pass anything through the App Store. You choose the method in **Dashboard → Settings → iPhone installs**: device matching (below), paste handoff (an exact one-time link the person allows to paste; reading it shows an "Allow Paste" prompt), both, or neither. Device matching starts off for new workspaces. Your app reads the choice from our server on its first open, so changing it needs no app release. Device matching works like this:

1. Someone without your app taps the link in Safari and sees a page with a **Get the app** button.
2. Tapping it records a coarse device signature together with the link, then opens the App Store.
3. On first launch, the SDK sends the same coarse fields to `/v1/match`. If a signature from the last **1 hour** matches, your app gets the link.

The signature is made from:

| Input | From |
|---|---|
| Screen width and pixel ratio | The browser, then the app |
| Language and time zone | The browser, then the app |
| iOS major version | The browser's user agent, then the app's |
| Network: prefix, operator (ASN) and a keyed hash of the full IP | Seen by our server; never sent by the app |

Each saved signature can be matched **once** and expires after one hour. It's never used to identify anyone across apps or sites.

What we use, how long we keep it, why there's no ATT prompt, the four combinations of the two switches, paste handoff (an exact match the person allows) and a ready-made App Store privacy label are all in [How iPhone install matching works](https://straitlink.in/docs/iphone-install-matching/).

> **Probabilistic, and opt-in**
>
> Two people on the same network with the same phone model, language and time zone who tap different links within the hour are **not matched at all**: when taps look alike, we refuse rather than guess, so neither install is sent to the wrong screen. Each match in Analytics shows its method, so you can see how installs were matched. iPhone matching is proven on iPhone and iPad simulators; the real-iPhone run waits on our own App Store listing.

Either way, a matched install comes back to the app with its tap id, so purchases made afterwards are credited to that tap (see [Purchases](https://straitlink.in/docs/analytics/#purchases)).

## Match methods

Every install in Analytics shows how it was matched:

| Method | Meaning |
|---|---|
| `install_referrer` | Exact, from the Google Play referrer |
| `exact_ext` | iPhone signature matched on every input |
| `exact_core` | iPhone signature matched on the core inputs |
| `scored` | iPhone signals scored against recent taps; used only in workspaces where Strait has turned scored matching on |
| `clipboard` | iPhone clipboard boost: the one-time handoff link from the tap page (exact) |
| `none` | No match: organic install, or the match window passed |

## Once per install

The deferred check runs once per install. It's skipped (and marked done) when the first launch was itself opened by a link, so a direct open is never followed by a stale deferred jump. If the phone is offline on first launch, the check runs again next launch.
