refactor: Process link (#38)

* refactor: rename API_KEY to apiKey

* refactor: update detour context type and usage

* refactor: improve examples and clean up types

* docs: improve deep link testing instructions and logic

* refactor: simplify type annotation in useDetour hook

Author: piaccho

README.md

@@ -66,7 +66,7 @@ import { Stack, usePathname, useRouter } from 'expo-router';
 SplashScreen.preventAutoHideAsync();
 
 export function RootNavigator() {
-  const { isLinkProcessed, linkRoute, clearLink } = useDetourContext();
+  const { isLinkProcessed, link, clearLink } = useDetourContext();
   const pathname = usePathname();
   const router = useRouter();
 
@@ -77,13 +77,13 @@ export function RootNavigator() {
   }, [isLinkProcessed]);
 
   useEffect(() => {
-    if (!isLinkProcessed || !linkRoute) return;
-    if (pathname !== linkRoute) {
-      router.replace(linkRoute);
+    if (!isLinkProcessed || !link) return;
+    if (pathname !== link.pathname) {
+      router.replace({ pathname: link.pathname, params: link.params });
       return;
     }
     clearLink(); // avoid redirecting again when returning to this screen
-  }, [clearLink, isLinkProcessed, linkRoute, pathname, router]);
+  }, [clearLink, isLinkProcessed, link, pathname, router]);
 
   if (!isLinkProcessed) {
     return null;
@@ -143,7 +143,7 @@ If you want to know more details about a given example and how to configure it,
 
 ## Clearing handled links
 
-If your app redirects based on `linkRoute` (especially in entry screens), call `clearLink()` after handling the route. This prevents repeated redirects when the user returns to the same screen.
+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
 
@@ -191,7 +191,7 @@ export type Config = {
 
 ### DetourContextType
 
-This type represents the object returned by the useDetourContext hook, containing the deferred link and its processing status.
+This type represents the object returned by the `useDetourContext` hook, containing the resolved link and its processing status.
 
 ```js
 export type DetourContextType = {
@@ -202,27 +202,43 @@ export type DetourContextType = {
   isLinkProcessed: boolean;
 
   /**
-   * The raw link URL (string or URL object), or null if no link was found.
+   * The resolved link object, or null if no link was found.
    */
-  linkUrl: string | URL | null;
+  link: DetourLink;
 
   /**
-   * The parsed route path derived from the link (e.g. '/details/42'), or null if no link was found.
+   * Resets the link to null. Call this after you handle a link.
    */
-  linkRoute: string | null;
+  clearLink: () => void;
+};
+```
 
-  /**
-   * The type of the detected link: 'deferred', 'verified' (Universal/App link), or 'scheme'.
-   * 'scheme' is only emitted when linkProcessingMode is 'all' (default).
-   * Null if no link was found.
-   */
-  linkType: LinkType | null;
+### DetourLink
+
+The resolved link object, or null if no link was found.
+
+```js
+export type DetourLink = {
+  /** The original link URL as received by the SDK. */
+  url: string | URL;
+
+  /** Full route path including query string (e.g. '/details/42?campaign=summer'). */
+  route: string;
+
+  /** Route path without query string (e.g. '/details/42'). */
+  pathname: string;
+
+  /** Parsed query parameters (e.g. { campaign: 'summer' }). */
+  params: Record<string, string>;
 
   /**
-   * Clears the current link context (route/url/type). Call this after you handle a link.
+   * The type of the detected link:
+   * - 'deferred': resolved from the Detour API on first app install
+   * - 'verified': Universal Link (iOS) or App Link (Android)
+   * - 'scheme': custom scheme deep link (only when linkProcessingMode is 'all')
    */
-  clearLink: () => void;
-  };
+  type: LinkType;
+} | null;
 ```
 
 ---

examples/expo-bare/README.md

@@ -33,6 +33,7 @@ If you need more complex routing flows with a specific navigation library, check
 - Install dependencies: `yarn install`
 - Configure this app in Detour Dashboard: `https://godetour.dev` using identifiers from `app.json` (for example `ios.bundleIdentifier`, `android.package`).
 - Use values from Dashboard from "API configuration" section to fill `.env` and update `app.json` with generated integration code.
-- Run prebuild for this example: `cd examples/expo-bare && npx expo prebuild`
-- Start the example from repo root: `yarn examples:expo-bare start`
-- Run on device/simulator: `yarn workspace @swmansion/react-native-detour-expo-bare ios` or `yarn workspace @swmansion/react-native-detour-expo-bare android`
+- Run prebuild for this example: `yarn prebuild`
+- Start the example: `yarn start`
+- Run on device/simulator: `yarn ios` or `yarn android`
+- Trigger test links: **deferred** — copy the link from Detour Dashboard before a fresh install, then install and launch (link resolves on first open). **Universal/App link** — open the link from Dashboard while the app is running. See **Test flow** for more detail.

examples/expo-bare/app.json

@@ -7,22 +7,24 @@
     "icon": "./assets/icon.png",
     "userInterfaceStyle": "light",
     "newArchEnabled": true,
+    "scheme": "detour-expo-bare",
     "splash": {
       "image": "./assets/splash-icon.png",
       "resizeMode": "contain",
       "backgroundColor": "#ffffff"
     },
     "ios": {
-      "supportsTablet": true,
-      "bundleIdentifier": "detourreactnative.expobare"
+      "bundleIdentifier": "detourreactnative.expobare",
+      "appleTeamId": "ABCDE12345",
+      "supportsTablet": true
     },
     "android": {
+      "package": "detourreactnative.expobare",
       "adaptiveIcon": {
         "foregroundImage": "./assets/adaptive-icon.png",
         "backgroundColor": "#ffffff"
       },
-      "edgeToEdgeEnabled": true,
-      "package": "detourreactnative.expobare"
+      "edgeToEdgeEnabled": true
     },
     "web": {
       "favicon": "./assets/favicon.png"

examples/expo-bare/package.json

@@ -6,7 +6,8 @@
     "start": "expo start",
     "android": "expo run:android",
     "ios": "expo run:ios",
-    "web": "expo start --web"
+    "web": "expo start --web",
+    "prebuild": "expo prebuild --clean"
   },
   "dependencies": {
     "@expo/metro-runtime": "~5.0.4",

examples/expo-bare/src/Screen.tsx

@@ -2,7 +2,7 @@ import { useDetourContext } from '@swmansion/react-native-detour';
 import { StyleSheet, Text, View } from 'react-native';
 
 export const Screen = () => {
-  const { isLinkProcessed, linkRoute, linkType, linkUrl } = useDetourContext();
+  const { isLinkProcessed, link } = useDetourContext();
 
   return (
     <View style={styles.container}>
@@ -23,16 +23,21 @@ export const Screen = () => {
         </Text>
 
         <Text style={styles.status}>
-          <Text style={styles.bold}>linkType:</Text> {linkType ?? 'none'}
+          <Text style={styles.bold}>type:</Text> {link?.type ?? 'none'}
         </Text>
 
         <Text style={styles.status}>
-          <Text style={styles.bold}>linkUrl:</Text> {String(linkUrl ?? 'none')}
+          <Text style={styles.bold}>url:</Text> {String(link?.url ?? 'none')}
+        </Text>
+
+        <Text style={styles.status}>
+          <Text style={styles.bold}>query params:</Text>{' '}
+          {link?.params ? JSON.stringify(link.params, null, 2) : 'none'}
         </Text>
 
         <Text style={styles.status}>
           <Text style={styles.resolvedLink}>Resolved route:</Text>{' '}
-          {linkRoute ? linkRoute : 'none'}
+          {link?.route ?? 'none'}
         </Text>
       </View>
     </View>

examples/expo-router-advanced/README.md

@@ -40,6 +40,7 @@ Optional custom scheme test:
 - Install dependencies: `yarn install`
 - Configure this app in Detour Dashboard: `https://godetour.dev` using identifiers from `app.json` (for example `ios.bundleIdentifier`, `android.package`).
 - Use values from Dashboard from "API configuration" section to fill `.env` and update `app.json` with generated integration code.
-- Run prebuild for this example: `cd examples/expo-router-advanced && npx expo prebuild`
-- Start the example from repo root: `yarn examples:expo-router-advanced start`
-- Run on device/simulator: `yarn workspace @swmansion/react-native-detour-expo-router-advanced ios` or `yarn workspace @swmansion/react-native-detour-expo-router-advanced android`
+- Run prebuild for this example: `yarn prebuild`
+- Start the example: `yarn start`
+- Run on device/simulator: `yarn ios` or `yarn android`
+- Trigger test links: **deferred** — copy the link from Detour Dashboard before a fresh install, then install and launch (link resolves on first open). **Universal/App link** — open the link from Dashboard while the app is running. **Custom scheme** — open `detour-expo-router-advanced://app/anything` directly. See **Test flow** for more detail.

examples/expo-router-advanced/app.json

@@ -14,16 +14,17 @@
       "backgroundColor": "#ffffff"
     },
     "ios": {
-      "supportsTablet": true,
-      "bundleIdentifier": "detourreactnative.exporouteradvanced"
+      "bundleIdentifier": "detourreactnative.exporouteradvanced",
+      "appleTeamId": "ABCDE12345",
+      "supportsTablet": true
     },
     "android": {
+      "package": "detourreactnative.exporouteradvanced",
       "adaptiveIcon": {
         "foregroundImage": "./assets/adaptive-icon.png",
         "backgroundColor": "#ffffff"
       },
-      "edgeToEdgeEnabled": true,
-      "package": "detourreactnative.exporouteradvanced"
+      "edgeToEdgeEnabled": true
     },
     "web": {
       "favicon": "./assets/favicon.png"

examples/expo-router-advanced/package.json

@@ -6,7 +6,8 @@
     "start": "expo start",
     "android": "expo run:android",
     "ios": "expo run:ios",
-    "web": "expo start --web"
+    "web": "expo start --web",
+    "prebuild": "expo prebuild --clean"
   },
   "dependencies": {
     "@expo/metro-runtime": "~5.0.4",

examples/expo-router-advanced/src/DetourGate.tsx

@@ -11,56 +11,55 @@ const getPathname = (route: string) => route.split('?')[0] || '/';
 // This component acts as a gate for incoming Detour links, coordinating with the auth state and routing logic of the app.
 // It should be placed inside the DetourProvider and rendered on all screens (e.g. in the root layout) to ensure that incoming links are handled correctly regardless of the current screen.
 export const DetourGate = () => {
-  const { isLinkProcessed, linkRoute, linkType, clearLink } =
-    useDetourContext();
+  const { isLinkProcessed, link, clearLink } = useDetourContext();
   const { isSignedIn, setPendingLink, setPendingLinkType } = useAuth();
   const router = useRouter();
 
   useEffect(() => {
     if (!isLinkProcessed) return;
 
     // No link to process, hide the splash screen and continue as normal.
-    if (!linkRoute) {
+    if (!link) {
       SplashScreen.hideAsync();
       return;
     }
 
     if (!isSignedIn) {
       // For signed-out users, keep the link as pending and continue with auth flow first.
-      setPendingLink(linkRoute);
-      setPendingLinkType(linkType);
+      setPendingLink(link.route);
+      setPendingLinkType(link.type);
       clearLink();
       SplashScreen.hideAsync();
       router.replace('/sign-in');
       return;
     }
 
-    const path = getPathname(linkRoute);
+    const path = getPathname(link.route);
 
     if (path !== ALLOWED_ROUTE) {
       // Example gate: only `/details` is accepted in this demo.
       clearLink();
       SplashScreen.hideAsync();
-      router.replace('/+not-found');
+      router.replace({
+        pathname: '/+not-found',
+        params: { path: link.route },
+      });
       return;
     }
 
-    const nextParams = linkType
-      ? { fromDeepLink: 'true', linkType }
-      : { fromDeepLink: 'true' };
-
     clearLink();
     SplashScreen.hideAsync();
     router.replace({
       pathname: '/(app)/details',
-      params: nextParams,
+      // Except of link query params the debuging params are passed here to show how link data was processed.
+      // You can remove them in production.
+      params: { fromDeepLink: 'true', linkType: link.type, ...link.params },
     });
   }, [
     clearLink,
     isLinkProcessed,
     isSignedIn,
-    linkRoute,
-    linkType,
+    link,
     router,
     setPendingLink,
     setPendingLinkType,

examples/expo-router-advanced/src/app/(app)/details.tsx

@@ -1,6 +1,7 @@
 import { Link, useLocalSearchParams } from 'expo-router';
 import { Platform } from 'react-native';
-import { Pressable, StyleSheet, Text, View } from 'react-native';
+import { Pressable, Text, View } from 'react-native';
+import { styles } from '../../styles';
 
 // This screen is the expected destination for Detour links resolving to /details.
 export default function DetailsScreen() {
@@ -15,6 +16,12 @@ export default function DetailsScreen() {
       default: linkType,
     });
   }
+  // Remove the debug params from the params object to show only the original link params.
+  const linkParams = Object.fromEntries(
+    Object.entries(params).filter(
+      ([key]) => key !== 'fromDeepLink' && key !== 'linkType'
+    )
+  );
 
   return (
     <View style={styles.screen}>
@@ -27,6 +34,14 @@ export default function DetailsScreen() {
             ? `Opened via deep link (${linkType} link)`
             : 'Opened via button navigation'}
         </Text>
+        {Object.keys(linkParams).length > 0 && (
+          <>
+            <Text style={styles.label}>Link parameters: </Text>
+            <Text style={styles.label}>
+              {JSON.stringify(linkParams, null, 2)}
+            </Text>
+          </>
+        )}
         <Text style={styles.instructions}>
           Trigger a Detour link that resolves to{' '}
           <Text style={styles.bold}>/details</Text> to validate this flow.
@@ -40,48 +55,3 @@ export default function DetailsScreen() {
     </View>
   );
 }
-
-const styles = StyleSheet.create({
-  screen: {
-    flex: 1,
-    justifyContent: 'center',
-    alignItems: 'center',
-    padding: 20,
-  },
-  card: {
-    padding: 24,
-    borderRadius: 12,
-    backgroundColor: '#f9fafb',
-    gap: 12,
-    alignItems: 'center',
-  },
-  title: {
-    fontSize: 20,
-    fontWeight: '600',
-  },
-  label: {
-    fontSize: 14,
-    color: '#6b7280',
-  },
-  instructions: {
-    fontSize: 13,
-    color: '#475569',
-  },
-  bold: {
-    fontWeight: '600',
-  },
-  value: {
-    fontWeight: '600',
-  },
-  button: {
-    marginTop: 8,
-    paddingHorizontal: 20,
-    paddingVertical: 10,
-    borderRadius: 8,
-    backgroundColor: '#111827',
-  },
-  buttonText: {
-    color: '#ffffff',
-    fontWeight: '600',
-  },
-});