docs: improve deep link testing instructions and logic

Author: piaccho

examples/expo-bare/README.md

@@ -36,3 +36,4 @@ If you need more complex routing flows with a specific navigation library, check
 - 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-router-advanced/README.md

@@ -43,3 +43,4 @@ Optional custom scheme test:
 - 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-native-intent/README.md

@@ -38,3 +38,4 @@ Result: when a universal/app link is opened, Expo Router receives the final rout
 - 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-router/README.md

@@ -24,3 +24,4 @@ For more advanced use case with authentication, see `examples/expo-router-advanc
 - 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/react-navigation-advanced/README.md

@@ -41,3 +41,4 @@ This example demonstrates an auth-gated React Navigation app with Detour integra
 - 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-react-navigation-advanced://details` directly. See **Test flow** for more detail.

examples/react-navigation-advanced/src/App.tsx

@@ -151,8 +151,12 @@ const AppRoot = () => {
       return;
     }
 
-    // toPendingDetailsRoute returns null for unrecognized paths, which allows us to show a NotFound screen for those while still handling known routes (e.g. /details/:id) that require authentication by saving a pending route if the user is not logged in.
-    const pending = toPendingDetailsRoute(link.route, 'detour');
+    // Convert the Detour link to a pending route if it's a known protected route that requires auth.
+    // This example only has one protected route (Details) but this logic can be extended as needed.
+    const pending = toPendingDetailsRoute(link.route, 'detour', {
+      linkType: link.type,
+      linkParams: link.params,
+    });
     clearLink();
 
     if (!pending) {
@@ -165,22 +169,11 @@ const AppRoot = () => {
 
     // If the user is not logged in, save the pending route and navigate to Login. Otherwise, navigate to the resolved route.
     if (!isLoggedIn) {
-      setPendingRoute({
-        ...pending,
-        params: {
-          ...pending.params,
-          linkType: link.type,
-          linkParams: link.params,
-        },
-      });
+      setPendingRoute(pending);
       navigationRef.navigate('Login');
       return;
     }
-    navigationRef.navigate(pending.name, {
-      ...pending.params,
-      linkType: link.type,
-      linkParams: link.params,
-    });
+    navigationRef.navigate(pending.name, pending.params);
   }, [
     clearLink,
     isLinkProcessed,

examples/react-navigation-advanced/src/navigation/helpers.ts

@@ -27,9 +27,12 @@ const normalizePath = (raw: string) => {
 // This helper function demonstrates how to parse incoming paths into pending route information for protected deep links specifically for the Details screen in this example.
 // Returning `null` means the link is silently discarded — no navigation occurs.
 // In a real app, this logic would likely be more complex and handle more routes and edge cases.
+// The `extra` parameter can include any additional information about the link that you want to include in the pending route params.
+// In this example, we include the original link type and parameters for demonstration purposes.
 export const toPendingDetailsRoute = (
   raw: string,
-  source: 'detour' | 'linking'
+  source: 'detour' | 'linking',
+  extra?: { linkType?: string; linkParams?: Record<string, string> }
 ): PendingRoute | null => {
   const path = normalizePath(raw);
   const pathname = path.split('?')[0] || '/';
@@ -40,7 +43,7 @@ export const toPendingDetailsRoute = (
 
   return {
     name: 'Details',
-    params: { fromDeepLink: true, source },
+    params: { fromDeepLink: true, source, ...extra },
   };
 };
 

examples/react-navigation-advanced/src/navigation/screens/Home.tsx

@@ -19,8 +19,15 @@ export function Home() {
         </Text>
         <Text style={styles.instructions}>
           Try to open links that resolve to the details screen e.g.:{' '}
-          <Text style={styles.bold}>/details</Text> or{' '}
-          <Text style={styles.bold}>/details?id=42</Text>.
+          <Text style={styles.bold}>/details</Text> (can include query
+          parameters).
+        </Text>
+        <Text style={styles.instructions}>
+          You can also test custom scheme links to see how they are handled by
+          React Navigation Linking without Detour processing, e.g.:{' '}
+          <Text style={styles.bold}>
+            detour-react-navigation-advanced://details
+          </Text>
         </Text>
         {pendingRoute && (
           <>

examples/react-navigation-advanced/src/navigation/screens/Login.tsx

@@ -14,11 +14,17 @@ export function Login() {
           resumes pending deep links after sign in.
         </Text>
         <Text style={styles.instructions}>
-          Try links resolving to <Text style={styles.bold}>/details</Text> or{' '}
-          <Text style={styles.bold}>/details?id=42</Text> while signed out. The
-          app should keep a pending target and continue after login.
+          Try links resolving to <Text style={styles.bold}>/details</Text> (can
+          include query parameters) while signed out. The app should keep a
+          pending target and continue after login.
+        </Text>
+        <Text style={styles.instructions}>
+          You can also test custom scheme links to see how they are handled by
+          React Navigation Linking without Detour processing, e.g.:{' '}
+          <Text style={styles.bold}>
+            detour-react-navigation-advanced://details
+          </Text>
         </Text>
-
         {pendingRoute && (
           <View style={styles.container}>
             <Text style={styles.sectionTitle}>Pending route</Text>

examples/react-navigation/README.md

@@ -28,3 +28,4 @@ This example demonstrates the minimal integration of `@swmansion/react-native-de
 - 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.