# Limitations & Known Issues

Deferred linking depends on the signals the platforms expose, and those signals
can be masked, stripped or absent. The sections below describe the edge cases
seen in real traffic, their cause, and their effect on attribution.

---

## Private Relay and VPNs

Several kinds of service change the client's IP address before it reaches Detour:

- iCloud Private Relay
- consumer VPNs
- corporate proxies

Private Relay is the most common. It masks the real IP and presents a relay IP instead, sometimes with a coarse region attached.

:::caution[Impact]

- IP equality is one of the strongest signals in probabilistic matching. A missing or altered IP lowers the total score and produces **false negatives**, that is matches that should have happened and did not.
- When the click carried one IP and the first open carries a relay IP, the equality check fails outright. Combined with otherwise weak signals, the candidate drops below the threshold.
  :::

### How Private Relay works

**iCloud Private Relay** is an opt-in iCloud+ service that proxies and encrypts traffic from Apple devices, so that no single party sees both who the user is and what sites they visit. Traffic takes two hops, an Apple-operated ingress relay and then a third-party egress relay, which masks the real IP address and DNS lookups while preserving the user's approximate region.

- **Who has it** — iCloud+ subscribers who turn it on in iCloud settings.
- **What it covers** — web browsing in Safari, plus other unencrypted app traffic the system can proxy. It runs in the OS networking stack and is not visible to the user once enabled.

:::tip[Improve iOS match rates]
Enable the copy-link feature for iOS users. The clipboard signal is not affected by Private Relay and raises the chance of a successful match.
:::

---

## iOS pasteboard permission

Clipboard contents are a strong probabilistic signal, but iOS restricts access to them. Reading the clipboard triggers a system prompt in some contexts, and users can decline it. In other flows the prompt never appears at all.

:::caution[Impact]

- Without paste access, the `pastedLink` signal is missing and the score drops accordingly.
- The copy-to-install flow depends on the user actually copying the link. Users who skip that step gain nothing from it.
  :::

---

## Redirect chains and referrer loss

Any service between the tap and Detour can rewrite the URL. Ad networks, trackers, and link shorteners routinely strip query parameters or referrer information, and on Android `click_id` is carried in those parameters.

:::caution[Impact]

- A missing `click_id` at install time rules out deterministic matching for that click. Detour falls back to probabilistic matching, which is less reliable.
- A redirect can also change the landing domain, in which case `assetlinks` verification runs against a different host.
  :::

---

## Play Store referrer missing

The Android Install Referrer usually delivers `referrer` data. It does not in these cases:

- The device has an enterprise account configured.

  Referrer data is reset automatically, even when a non-enterprise account is currently selected. This is a known Android platform limitation, tracked in the [Google Issue Tracker](https://issuetracker.google.com/issues/445826632).

- The link opened the Play Store website rather than the Play Store app.
- The install did not come from a normal store flow: pre-installs, sideloads, some Play Store variants, and internal or external test tracks.
- The Play Store and the app were not interacted with in the expected order, which can delay or lose the referrer.

:::caution[Impact]
Deterministic matching fails when the referrer is missing or malformed, and the install falls back to probabilistic matching.
:::

---

## In-app browsers block the App Store

Instagram, Threads, Facebook, and TikTok open links in their own webview on iOS,
and that webview refuses App Store URLs. A link placed in a bio or a caption is
opened there by default, so a deferred link that redirects to the App Store
stops at that point. The Meta webviews end on a blank page. TikTok shows an
error toast.

Only iOS App Store destinations are affected. Android in-app browsers follow
Play Store URLs normally, and a link whose destination is a web page loads in
all of these webviews.

Detour treats these apps differently:

- **Instagram and Threads** — Detour opens the App Store URL outside the webview, through another browser or the App Store app. If no hand-off goes through, the visitor stays on the page with a button to continue manually.
- **Facebook** — Detour first tries to open the installed app, through Safari for a link in a post or an ad, and through an **Open app** button for a link in a bio. Without the app, the visitor then reaches the App Store. If the visitor declines the Safari prompt, a tap on the **App Store** button opens the App Store.
- **Messenger** — the automatic redirect does not open the App Store. Detour shows the **App Store** button, and a tap opens the App Store.
- **TikTok** — no hand-off works. Detour skips the attempts, **App Preview**, and the iOS copy-link page, and tells the visitor to open the page in their own browser from the `•••` menu.

:::caution[Impact]

- A visitor who stays inside the webview never reaches the store, so that install does not happen.
- In Instagram, Threads, Messenger, and TikTok, the click is recorded before the redirect runs. Click counts therefore do not fall when this happens, and only the install count does.
- In Facebook, and for a link with the open-app flag, Detour records no click on page load. Your app records the click, or the page that sends the visitor to the store does. A visitor who leaves without opening the app or tapping a button is not counted.
- A visitor who leaves the webview and installs later can still be matched, because the recorded click stays available for the match window.
  :::

For the hand-off in each app, see
[Links in Social Apps](https://detour.swmansion.com/docs/platform/architecture/social-app-links).

---

## Frozen OS version on iOS 26

Safari on iOS 26 reports `CPU iPhone OS 18_7` in the user agent regardless of
the real iOS version. The device signal on iOS is exactly that comparison: the
OS version from the click's user agent against the `systemVersion` the SDK
reports. A frozen token makes it fail.

Detour reads the true version from Safari's `Version/` token instead.

:::caution[Impact]
A browser that sends the frozen token and no `Version/` token scores **0** for
the device signal, and iOS has no second device check to fall back on (see
[Scoring weights](https://detour.swmansion.com/docs/platform/architecture/matching#scoring-weights)). The
candidate has to clear the threshold on its remaining signals alone.
:::

:::tip[Workaround]
Enable the copy-link feature. On such browsers the clipboard signal is usually
what raises the score above the threshold.
:::

---

## False positives and false negatives

Probabilistic matching is a heuristic. It combines signals and accepts anything above a threshold, so there are two kinds of error:

- **False negative** — a correct match is missed, because the score fell below the threshold.
- **False positive** — the wrong click is matched, because its score cleared the threshold.

:::caution[Impact]

- A false negative loses the deferred attribution, and the user does not reach the content the link pointed to.
- A false positive corrupts your analytics, and the user reaches the wrong content.
  :::

---

## Shared devices and shared IPs

Shared households, corporate devices, and NATs all produce similar fingerprints and identical IPs for several distinct users.

:::caution[Impact]

- Two users clicking different links on the same device or network within a short window raise the risk of a false positive.
- Attribution on shared devices is hard to interpret, even when it is technically correct.
  :::