@uselinking/react-native

Deferred deep linking for React Native / Expo.

When someone taps your link without the app installed, they go to the App Store or Play Store — and the link's intent is lost. This SDK carries it across that gap: on the first launch after install, your app receives the link that was tapped and can open the right screen.

Client SDK for uselinking.com.

Install

npx expo install @uselinking/react-native @react-native-async-storage/async-storage

Add the config plugin to app.json / app.config.js with your link domain — it sets up the iOS Associated Domains entitlement and the Android autoVerify intent filter, which is the step most integrations get wrong:

{
  "expo": {
    "plugins": [
      ["@uselinking/react-native", { "linkDomain": "yourapp.lnk.uselinking.com" }]
    ]
  }
}

This changes native config, so rebuild the app (expo prebuild + a native build, or an EAS build) — an OTA update is not enough.

Use

import { DeepLinkProvider, useDeferredLink } from '@uselinking/react-native';

export default function App() {
  return (
    <DeepLinkProvider config={{ apiKey: 'dlk_live_…' }}>
      <Root />
    </DeepLinkProvider>
  );
}

function Root() {
  const { isLinkProcessed, link, clearLink } = useDeferredLink();

  useEffect(() => {
    if (!isLinkProcessed || !link) return;
    navigate(link.path, link.params); // e.g. "/events/join", { it: "abc123" }
    clearLink();
  }, [isLinkProcessed, link]);
}

Imperative API, for gating startup on the match:

import { init, getInitialLink, waitForInitialLink } from '@uselinking/react-native';

init({ apiKey: 'dlk_live_…' });
await waitForInitialLink(5000); // resolves when the attempt settles, or times out
const link = await getInitialLink(); // null on later launches

Match confidence

link.matchType tells you how sure the server is, so you can decide what to trust:

value	meaning
unique	Exactly one pending click matched every signal. Safe to act on.
weak	Only one click was pending, but a signal disagreed (e.g. locale). Probably right.
—	No confident match: link is null and the app does its normal first launch.

Android uses the Play Install Referrer, which is deterministic — a match there is always unique. iOS has no equivalent (the App Store passes nothing through), so matching is probabilistic and fails open: when two clicks are ambiguous the SDK returns nothing rather than risk opening the wrong screen.

Notes

• One match attempt per install, on the first launch. Later launches resolve from local storage immediately.
• The response is persisted before it is delivered, so a crash during startup doesn't lose the link.
• Network failures settle as "no link" and retry on the next launch — the SDK never blocks or breaks app startup.
• No cross-app tracking, no advertising identifiers. Signals are used once to match your own link, then the pending click is consumed.

License

MIT