Expo Router SDK

Bridge LocusVia link resolution into Expo Router's native-intent lifecycle.

Choose this SDK when#

Use this guide when Expo Router owns your React Native navigation and incoming operating-system URLs must become Stack or Tabs routes.

Warning

The Expo Router adapter ships as the published @locusvia/react-native-sdk/expo-router subpath. Expo Router 3 or later is required.

Choose another SDK when: you use bare React Navigation without Expo Router; mount the standard React Native provider instead.

Before you start#

An Expo Router application with native iOS and/or Android projects available for association configuration.
A LocusVia App Platform ID, SDK key, and API origin from the same environment.
Route names that can accept the resolved pathname and parameters.

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 React Native package; the Expo adapter is included as a subpath export.

bash

npm install @locusvia/react-native-sdk

2. Mount the provider#

Place the provider above the root Stack or Tabs layout so one lifecycle owns deferred and runtime link state.

tsx

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

export default function RootLayout() {
  return (
    <LocusViaProvider config={locusViaConfig}>
      <Stack />
    </LocusViaProvider>
  );
}

3. Bridge native intents#

Use the Expo Router subpath at the native-intent boundary, then route the resolved pathname through your existing Stack or Tabs structure.

tsx

import { createNativeIntentHandler } from "@locusvia/react-native-sdk/expo-router";

export const redirectSystemPath = createNativeIntentHandler({
  hosts: ["go.example.com"],
  fallbackPath: "/",
  config: {
    appID: "REPLACE_WITH_APP_ID",
    apiKey: "REPLACE_WITH_SDK_KEY",
  },
  mapToRoute: ({ resolvedUrl }) => resolvedUrl.pathname || "/",
});

Verify the integration#

Launch from a verified link with the app stopped and confirm Expo Router selects the expected screen.
Open a second link while the app is foregrounded and confirm the native-intent path changes once.
Test a no-match URL and confirm the router remains on the safe default route.

Warning

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

Troubleshoot by symptom#

Router receives the raw URLEnsure the native-intent boundary calls the LocusVia handler before mapping the path to a screen.

Works in Expo Go onlyVerify the development or production native build; Expo Go does not prove your app's association entitlements.

Cold start hangsKeep a bounded loading state and return the safe default route when resolution is not found or fails.

Wrong environment responseAlign app ID, SDK key, and API origin; environment mismatches fail closed.

Next steps#

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