React Native SDK

Handle initial, deferred, and runtime links from one application provider.

Choose this SDK when#

Use this guide for bare React Native applications where one root provider can own link startup, runtime listeners, and analytics forwarding.

Warning

@locusvia/react-native-sdk 0.1.3 is published on npm. React Native 0.72 or later and React 18 or later are supported.

Choose another SDK when: Expo Router owns navigation; use the Expo Router guide so native intents enter the router pipeline correctly.

Before you start#

A configured iOS App Platform and/or Android App Platform with verified domain associations.
A LocusVia App Platform ID, SDK key, and API origin from the same environment.
A root component that remains mounted for the application lifetime.

Note

Use an environment-scoped public SDK key. Never embed a server, admin, or privileged credential in an app.

1. Install the package#

Install the published package. Add Async Storage only when persisted link state is required.

bash

npm install @locusvia/react-native-sdk

2. Mount the provider once#

Wrap the root application. On mount it checks the initial URL, attempts deferred resolution when appropriate, and listens for runtime links.

tsx

import { LocusViaProvider } from "@locusvia/react-native-sdk";

<LocusViaProvider config={{
  appID: "REPLACE_WITH_APP_ID",
  apiKey: "REPLACE_WITH_SDK_KEY",
  baseUrl: "https://staging.locusvia.com",
}}>
  <App />
</LocusViaProvider>

3. Route a resolved link#

Read the provider result in the screen boundary and navigate only when a link is present. Keep the normal home path for not-found results.

tsx

const { lastLink, isResolving } = useLocusVia();
const { link } = useDeferredLink(lastLink, isResolving);

useEffect(() => {
  if (!isResolving && link?.pathname) navigation.navigate(link.pathname);
}, [link, isResolving, navigation]);

Verify the integration#

Open a verified link from a force-stopped signed iOS and Android app and confirm the target route.
Install after following a fallback link and confirm the first launch recovers the deferred destination.
Open another link while the app is foregrounded and confirm it routes once without remounting the provider.

Warning

A successful build proves source compatibility only. Test a real link on the target browser or signed device before release.

Troubleshoot by symptom#

Provider stays on the normal routeInspect loading, link, and error states; confirm the app ID, SDK key, and API origin share one environment.

Link opens the browserCorrect Associated Domains, Android intent filters, and the live association files before debugging SDK code.

Runtime links fire twiceMount one provider at the application root and remove any duplicate Linking listeners.

Deferred link repeatsPersist and consume the deferred result once at the journey boundary.

Next steps#

Confirm your domain associations, then add conversion and revenue events only after link resolution works end to end.