# Testing & Troubleshooting

Testing deferred linking has platform constraints. The complete deferred flow requires the store redirect chain, that is the App Store or Google Play.

## Testing iOS

If your app is not yet released:

1. Remove any existing install from the device so the next open counts as a first launch.
2. Open a Detour link in a mobile browser.
3. Expect the App Store redirect to fail. With no public listing yet, the store has no listing to open, which does not affect the test.
4. Install your development build.
5. Launch the app and confirm the link resolves within the matching window (currently 15 minutes).

## Testing Android

For non-production builds, the install referrer often does not work in store test tracks, so deterministic matching can be unavailable.
You can still verify the probabilistic flow:

1. Uninstall the app from the device.
2. Open a Detour link in a mobile browser.
3. Expect the Play Store redirect to fail when the production listing is unavailable.
4. Install your development build.
5. Launch the app and confirm the link resolves within the matching window (currently 15 minutes).

For local install referrer testing workarounds, see
[How to test the Play Store Install Referrer API](https://medium.com/@madicdjordje/how-to-test-the-play-store-install-referrer-api-78a63d59945b).

:::note[Missing `click_id`]
If you encounter click_id missing in your build see limitations section [Play Store referrer missing](https://detour.swmansion.com/docs/platform/architecture/architecture-limitations#play-store-referrer-missing)
:::

## Testing Android App Links

Whether an installed app opens a Detour link depends on the Dashboard SHA-256 matching the key that signed **the build on your device**:

| Installation method                                     | SHA-256 to configure                   | Where to find it                                                                                         |
| :------------------------------------------------------ | :------------------------------------- | :------------------------------------------------------------------------------------------------------- |
| Google Play, any track                                  | Play App Signing key                   | Play Console → **Protected with Play** → **Manage Play app signing** → *App signing key certificate*     |
| `eas build`, any profile, including `development`       | Keystore in your EAS account           | `eas credentials -p android` → profile → **Keystore** → `SHA256 Fingerprint`                             |
| `npx expo run:android` / `npx react-native run-android` | Project's `android/app/debug.keystore` | `keytool -list -v -keystore android/app/debug.keystore -storepass android`, or `./gradlew signingReport` |

To check any build directly: `apksigner verify --print-certs app-debug.apk`. The complete procedure is described in [Finding your Android SHA-256 fingerprint](https://detour.swmansion.com/docs/platform/fundamentals/universal-app-links#finding-your-android-sha-256-fingerprint).

## Common issues

- No match found (`404`)
  - click is older than matching window
  - click was not recorded in Dashboard logs
  - for deterministic Android flow: missing `click_id` in referrer
- `429 Too Many Requests`
  - add retry/backoff and avoid heavy testing with one key across many devices
- iOS clipboard prompt not appearing
  - check `shouldUseClipboard: true`
  - verify copy-link flow is enabled in Dashboard
- iOS Universal Link opens the browser instead of the app during development
  - before your domain and App Store listing have fully propagated, iOS resolves the `apple-app-site-association` file through Apple's CDN, which may not have it yet
  - append `?mode=developer` to the matching entry in your iOS `associatedDomains` (e.g. `applinks:yourorg.godetour.link?mode=developer`) so the device fetches the association file directly from your server, bypassing the CDN
  - this also requires enabling **Developer Mode** on the test device (Settings → Privacy & Security → Developer Mode). Remove the `?mode=developer` suffix before shipping
- Link processed twice
  - confirm you call `clearLink()` after navigation
  - confirm exactly one `DetourProvider` instance is mounted
- Link is not processed on Expo Web
  - web runtime is intentionally unsupported
  - provider on web returns a no-op context and skips SDK initialization

## Bare React Native CLI build issues

These apply only to bare React Native CLI projects that added Expo Modules with `install-expo-modules` (see [Bare React Native projects](https://detour.swmansion.com/docs/sdk/react-native/2.0.0/sdk-installation#bare-react-native-projects)). They are bundler/environment issues, not SDK bugs. The SDK itself is plain JavaScript.

| Symptom                                                                                                                | Cause                                                                                                      | Fix                                                                                                                                                        |
| :--------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
| iOS: `TypeError: Cannot read property '…' of undefined` at startup                                                     | Expo Modules native code is not linked                                                                     | Run `npx install-expo-modules@latest`, then reinstall CocoaPods                                                                                            |
| Android release: `Serializer did not return expected format … Unexpected token 'v', "var __BUND"... is not valid JSON` | `metro.config.js` uses `@react-native/metro-config` while the build bundles with Expo CLI (`export:embed`) | Make `metro.config.js` extend `expo/metro-config`. See [Expo Modules setup](https://detour.swmansion.com/docs/sdk/react-native/2.0.0/sdk-installation#expo-modules-setup-react-native-cli) |
| `The NODE_ENV environment variable is required but was not specified`                                                  | `export:embed` ran without an environment set                                                              | Set `NODE_ENV=production` for the release build                                                                                                            |
| `cliFile … is not a file … it was a directory`                                                                         | `@expo/cli` is not hoisted to the top-level `node_modules`                                                 | Install it at the project root (`npm install @expo/cli@<version>`) or do a clean reinstall                                                                 |
| Bundling fails because `node` is not found                                                                             | `node` is not on the PATH of the Gradle process (common with `nvm`)                                        | Make sure `node` is on PATH for the build and restart the Gradle daemon (`./gradlew --stop`)                                                               |

For integration patterns that are easy to test end-to-end, use [Examples](https://detour.swmansion.com/docs/sdk/react-native/examples).