docs: update readme

BrtqKr · BrtqKr · commit d5eaebb80961 · 2026-06-01T14:10:06.000+02:00
diff --git a/README.md b/README.md
@@ -6,25 +6,17 @@
 
 # React Native Detour
 
-SDK for handling deferred links in React Native.
-
-## Create an account
-
-You need a Detour account to generate app credentials and configure your links.  
-Sign up here: [https://godetour.dev/auth/signup](https://godetour.dev/auth/signup)
+React Native Detour is an SDK for handling deferred deep links in React Native. A deferred link works like a regular deep link, but survives the App Store or Play Store install — a user who clicks a link before having the app installed is redirected to the right screen on first launch. Detour also handles Universal/App links and custom scheme links in a single unified API.
 
 ## Quick links
 
-- Documentation: [https://docs.swmansion.com/detour/docs/](https://docs.swmansion.com/detour/docs/)
-- Installation guide: [https://docs.swmansion.com/detour/docs/sdk/react-native/sdk-installation](https://docs.swmansion.com/detour/docs/sdk/react-native/sdk-installation)
-
-## Other Detour SDKs
+- Documentation: [https://detour.swmansion.com/docs/](https://detour.swmansion.com/docs/)
+- Installation guide: [https://detour.swmansion.com/docs/sdk/react-native/sdk-installation](https://detour.swmansion.com/docs/sdk/react-native/sdk-installation)
 
-Detour is also available for other app stacks:
+## Create an account
 
-- Android SDK: [https://github.com/software-mansion-labs/android-detour](https://github.com/software-mansion-labs/android-detour)
-- iOS SDK: [https://github.com/software-mansion-labs/ios-detour](https://github.com/software-mansion-labs/ios-detour)
-- Flutter SDK: [https://github.com/software-mansion-labs/detour-flutter-plugin](https://github.com/software-mansion-labs/detour-flutter-plugin)
+You need a Detour account to generate app credentials and configure your links.  
+Sign up here: [https://godetour.dev/auth/signup](https://godetour.dev/auth/signup)
 
 ## Installation
 
@@ -48,19 +40,33 @@ npm install expo-device
 npm install react-native-device-info
 ```
 
-> You can override the default persistent storage (@react-native-async-storage/async-storage) by providing an alternative storage implementation. Pass your custom storage object via the configuration settings.
+> You can override the default persistent storage (`@react-native-async-storage/async-storage`) by providing an alternative storage implementation via the `storage` config option.
+>
+> For device info, install either `expo-device` or `react-native-device-info` — at least one is required. If your project already uses one of them, no extra installation is needed.
 
 ## Usage
 
-### Initialize the provider
+Mount `DetourProvider` at the root of your app and configure it with your credentials. How you consume the resolved link depends on your navigation library.
+
+> The SDK is a no-op on Expo Web — `DetourProvider` mounts but link processing is skipped and `isLinkProcessed` resolves immediately to `true`.
+
+### Expo Router
+
+Wrap your root layout with `DetourProvider`, then use the `useDetourContext` hook to read the resolved link and drive navigation. If your app uses Expo Router's `+native-intent.tsx` to handle Universal/App links, import `createDetourNativeIntentHandler` from `@swmansion/react-native-detour/expo-router` and set `linkProcessingMode: 'deferred-only'` — Detour will only handle deferred links and let the native intent handler take care of the rest. See [`examples/expo-router-native-intent`](./examples/expo-router-native-intent) for a working setup.
+
+<details>
+<summary>Expo Router example</summary>
 
-```js
-import { DetourProvider, type Config } from '@swmansion/react-native-detour';
+```tsx
+import { DetourProvider, useDetourContext, type Config } from '@swmansion/react-native-detour';
+import { Stack, usePathname, useRouter } from "expo-router";
+import * as SplashScreen from "expo-splash-screen";
+
+SplashScreen.preventAutoHideAsync();
 
 const config: Config = {
   apiKey: '<REPLACE_WITH_YOUR_API_KEY>',
   appID: '<REPLACE_WITH_APP_ID_FROM_PLATFORM>',
-  shouldUseClipboard: true,
 };
 
 export default function RootLayout() {
@@ -70,19 +76,8 @@ export default function RootLayout() {
     </DetourProvider>
   );
 }
-```
 
-### Example (Expo Router)
-
-```js
-import { Stack, usePathname, useRouter } from "expo-router";
-import * as SplashScreen from "expo-splash-screen";
-
-import { useDetourContext } from "@swmansion/react-native-detour";
-
-SplashScreen.preventAutoHideAsync();
-
-export function RootNavigator() {
+function RootNavigator() {
   const { isLinkProcessed, link, clearLink } = useDetourContext();
   const pathname = usePathname();
   const router = useRouter();
@@ -99,7 +94,7 @@ export function RootNavigator() {
       router.replace({ pathname: link.pathname, params: link.params });
       return;
     }
-    clearLink(); // avoid redirecting again when returning to this screen
+    clearLink();
   }, [clearLink, isLinkProcessed, link, pathname, router]);
 
   if (!isLinkProcessed) {
@@ -110,40 +105,70 @@ export function RootNavigator() {
 }
 ```
 
-Learn more about usage from our [docs](https://docs.swmansion.com/detour/docs/SDK/sdk-usage)
+</details>
 
-### React Navigation linking integration
+### React Navigation
 
-When integrating with React Navigation's custom linking API (`getInitialURL` + `subscribe`), use Detour as the URL source:
+#### v2.2.2 and later
 
-```ts
-import { DETOUR_LINKING_PREFIX, Detour } from "@swmansion/react-native-detour";
+Pass Detour's linking adapter to `NavigationContainer`. React Navigation will handle routing automatically — `useDetourContext` is not needed for basic usage. The splash screen is hidden via `onReady`, which fires after `getInitialURL` resolves.
+
+<details>
+<summary>React Navigation example</summary>
+
+```tsx
+import { DetourProvider, DETOUR_LINKING_PREFIX, Detour, type Config } from '@swmansion/react-native-detour';
+import { NavigationContainer } from '@react-navigation/native';
+import * as SplashScreen from 'expo-splash-screen';
+
+SplashScreen.preventAutoHideAsync();
+
+const config: Config = {
+  apiKey: '<REPLACE_WITH_YOUR_API_KEY>',
+  appID: '<REPLACE_WITH_APP_ID_FROM_PLATFORM>',
+};
 
 const linking = {
   prefixes: [DETOUR_LINKING_PREFIX],
   async getInitialURL() {
     return await Detour.getInitialURL();
   },
   subscribe(listener) {
-    const subscription = Detour.addEventListener("url", ({ url }) => {
+    const subscription = Detour.addEventListener('url', ({ url }) => {
       listener(url);
     });
-
     return () => subscription.remove();
   },
 };
+
+export function App() {
+  return (
+    <DetourProvider config={config}>
+      <NavigationContainer linking={linking} onReady={() => SplashScreen.hideAsync()}>
+        <Navigation />
+      </NavigationContainer>
+    </DetourProvider>
+  );
+}
 ```
 
-`DETOUR_LINKING_PREFIX` is an internal adapter prefix used for Detour-resolved routes.
-This API requires `DetourProvider` to be mounted above your `NavigationContainer`.
+</details>
+
+#### Before v2.2.2
+
+Use `useDetourContext` and call your navigator imperatively, the same way as the [Expo Router approach](#expo-router) above.
 
-See React Navigation docs:
-https://reactnavigation.org/docs/deep-linking?config=static#integrating-with-other-tools
+#### Auth-gated apps
+
+The adapter appends `fromDeepLink=true` and `linkType` query params to every URL it emits — you will see these in your route params.
 
 For auth-gated apps, let React Navigation hold the deep link until the right screen is reachable.
 Render screens conditionally on auth/onboarding state and opt in to React Navigation's pending-link
 behavior on the navigator:
 
+<details>
+<summary>Auth-gated navigator example</summary>
+
 ```tsx
 <Stack.Navigator UNSTABLE_routeNamesChangeBehavior="lastUnhandled">
   {isSignedIn
@@ -157,10 +182,13 @@ behavior on the navigator:
 </Stack.Navigator>
 ```
 
-A deep link that arrives while the user is signed-out is parsed, found unreachable (the target
-screen isn't currently rendered), and remembered. When the rendered screen set changes — after
-sign-in, then again after onboarding — React Navigation retries and lands the user on the target.
-See `examples/react-navigation-advanced` for a working setup.
+</details>
+
+A deep link that arrives while the user is signed-out is parsed, found unreachable, and remembered. When the rendered screen set changes after sign-in or onboarding, React Navigation retries and lands the user on the target. See [`examples/react-navigation-advanced`](./examples/react-navigation-advanced) for a working setup.
+
+See the [React Navigation deep linking docs](https://reactnavigation.org/docs/deep-linking?config=static#integrating-with-other-tools).
+
+Learn more from our [docs](https://detour.swmansion.com/docs/SDK/sdk-usage).
 
 ### Controlling which links Detour processes
 
@@ -172,7 +200,10 @@ Use `linkProcessingMode` to control which link sources the SDK listens to:
 | `'web-only'`      | ✅                  | ✅             | ❌                  |
 | `'deferred-only'` | ❌                  | ✅             | ❌                  |
 
-```js
+<details>
+<summary>linkProcessingMode config example</summary>
+
+```ts
 const config: Config = {
   apiKey: '<REPLACE_WITH_YOUR_API_KEY>',
   appID: '<REPLACE_WITH_APP_ID_FROM_PLATFORM>',
@@ -182,8 +213,32 @@ const config: Config = {
 };
 ```
 
+</details>
+
 Use `'deferred-only'` when Expo Router's `+native-intent.tsx` handler is already resolving runtime Universal/App links — this prevents double-processing.
 
+### Clearing handled links
+
+If your app redirects based on `link` (especially in entry screens), call `clearLink()` after handling the route. This prevents repeated redirects when the user returns to the same screen.
+
+## Analytics
+
+The SDK includes a built-in analytics module. `DetourProvider` automatically tracks app opens for retention. You can also log custom events using the predefined `DetourEventNames` enum:
+
+<details>
+<summary>Analytics example</summary>
+
+```ts
+import { DetourAnalytics, DetourEventNames } from '@swmansion/react-native-detour';
+
+DetourAnalytics.logEvent(DetourEventNames.Purchase);
+DetourAnalytics.logRetention('week_1');
+```
+
+</details>
+
+See the [analytics docs](https://detour.swmansion.com/docs/) for the full event list and retention tracking setup.
+
 ## Examples
 
 All example apps with Detour SDK integrated live in `examples/`:
@@ -231,10 +286,6 @@ pnpm android
 
 > Running `pnpm ios` / `pnpm android` produces a development build. This is recommended over Expo Go for testing deep linking flows on a real device.
 
-## Clearing handled links
-
-If your app redirects based on `link` (especially in entry screens), call `clearLink()` after handling the route. This prevents repeated redirects when the user returns to the same screen.
-
 ## Types
 
 The package exposes several types to help you with type-checking in your own codebase.
@@ -243,7 +294,10 @@ The package exposes several types to help you with type-checking in your own cod
 
 This type is used to define the configuration object you pass to the DetourProvider.
 
-```js
+<details>
+<summary>Config type</summary>
+
+```ts
 export type Config = {
   /**
    * Your application ID from the Detour dashboard.
@@ -257,7 +311,8 @@ export type Config = {
 
   /**
    * Optional: A flag to determine if the provider should check the clipboard for a deferred link.
-   * Note: This feature is iOS-only. On Android, clipboard is never accessed regardless of this setting.
+   * Note: This feature is iOS-only. On Android, the SDK uses the install referrer for deterministic
+   * link matching instead; clipboard is never accessed regardless of this setting.
    * When enabled on iOS, it may display a permission alert to the user.
    * Defaults to true if not provided.
    */
@@ -279,11 +334,16 @@ export type Config = {
 };
 ```
 
+</details>
+
 ### DetourContextType
 
 This type represents the object returned by the `useDetourContext` hook, containing the resolved link and its processing status.
 
-```js
+<details>
+<summary>DetourContextType type</summary>
+
+```ts
 export type DetourContextType = {
   /**
    * Boolean indicating if the initial link (deferred, Universal/App Link, or scheme) has been processed.
@@ -303,11 +363,16 @@ export type DetourContextType = {
 };
 ```
 
+</details>
+
 ### DetourLink
 
 The resolved link object, or null if no link was found.
 
-```js
+<details>
+<summary>DetourLink type</summary>
+
+```ts
 export type DetourLink = {
   /** The original link URL as received by the SDK. */
   url: string | URL;
@@ -331,9 +396,14 @@ export type DetourLink = {
 } | null;
 ```
 
+</details>
+
 ### React Navigation adapter types
 
-```js
+<details>
+<summary>React Navigation adapter types</summary>
+
+```ts
 export const DETOUR_LINKING_PREFIX: string; // "detour://"
 
 export type DetourUrlEvent = {
@@ -345,11 +415,21 @@ export type DetourUrlSubscription = {
 };
 ```
 
-```js
+```ts
 Detour.getInitialURL(): Promise<string | undefined>
 Detour.addEventListener("url", (event: DetourUrlEvent) => void): DetourUrlSubscription
 ```
 
+</details>
+
+## Other Detour SDKs
+
+Detour is also available for other app stacks:
+
+- Android SDK: [https://github.com/software-mansion-labs/android-detour](https://github.com/software-mansion-labs/android-detour)
+- iOS SDK: [https://github.com/software-mansion-labs/ios-detour](https://github.com/software-mansion-labs/ios-detour)
+- Flutter SDK: [https://github.com/software-mansion-labs/detour-flutter-plugin](https://github.com/software-mansion-labs/detour-flutter-plugin)
+
 ---
 
 ## License
