# Usage

### Initialize provider in root of your app

```js
import { DetourProvider, type Config } from "@swmansion/react-native-detour";

const config: Config = {
  API_KEY: "<REPLACE_WITH_YOUR_API_KEY>",
  appID: "<REPLACE_WITH_APP_ID_FROM_PLATFORM>",
  shouldUseClipboard: true,
};

export default function RootLayout() {
  return (
    <DetourProvider config={config}>
      <RootNavigator />
    </DetourProvider>
  );
}
```

:::caution[Keep credentials in .env]
Keep your API_KEY and appID in .env
:::

### Use values from context - Example with Expo Router

SDK exposes `useDetourContext()` hook that returns object containing information about link and processing status. Our recommendation is to use the hook before you application renders navigation container.

The SDK only looks for a deferred link during the application's first launch after installation. Subsequent launches should be handled by Universal Links for iOS and App Links for Android. Deep links based on uri-scheme are also supported.

```js
import { useDetourContext } from "@swmansion/react-native-detour";
import * as SplashScreen from "expo-splash-screen";
import { Redirect, Stack } from "expo-router";

SplashScreen.preventAutoHideAsync();

export function RootNavigator() {
  const { isLinkProcessed, linkRoute, linkType, linkUrl } = useDetourContext();

  useEffect(() => {
    if (isLinkProcessed) {
      SplashScreen.hide();
    }
  }, [isLinkProcessed]);

  if (!isLinkProcessed) {
    return null;
  }

  if (linkRoute) {
    return <Redirect href={linkRoute} />;
  }

  return <Stack />;
}
```

`route` is ready to use path with params for your redirection. It contains everything you added to our generated link. You can use it to redirect to other screen in you app with any navigation solution you prefer.

**Example of route generation:**<br />
URL: `https://example-organization.godetour.link/Ar8UqUjGzG/segment1?param1=value1`<br />
route: `/segment1?param1=value1`

### Implementation & lifecycle details (important for integrators)

- On first app launch after install:
  - provider checks `AsyncStorage` / persisted flag to determine "first entrance".
  - provider sets an in-memory flag (so remounts in the same process won't trigger extra runs).
  - provider will either:
    - use `clickId` (if Android install referrer is present) → deterministic match
    - or build `ProbabilisticFingerprint` → probabilistic match
- The hook (`useDetourContext()`) exposes the final state. Wait for `isLinkProcessed` before you attempt to route the user.
- Matching is asynchronous. Show a loading state while it runs, then route to the matched content.
- Clipboard: including `pastedLink` improves match accuracy but may surface a paste permission prompt (iOS). Make this configurable in `Config.shouldUseClipboard` for UX control.
- On subsequent launches SDK checks only for universal/app links and process them

### Universal and App Links with Expo Router

Expo Router handles Universal Links and App Links natively. When it detects that the app was opened by such a link, it redirects to the corresponding route before the SDK can process the link.

**Important**: Remember that the route detected by Expo Router will contain the necessary **hash** that Detour uses for link identification. You must either match this route within your navigation structure or implement a catch-all mechanism for unassigned routes in your application.

Example implementation of `app/[...unmatched].tsx`:

```js
export default function UnmatchedRoute() {
  // Redirect immediately to place where you handle Detour response
  return <Redirect href="/" />;
}
```

This way you can rely on `linkRoute` from `useDetourContext()` which does not contain hash