Testing and Troubleshooting

Testing deferred linking has platform constraints: full deferred flow requires store redirect chain (App Store / Play Store).

Testing iOS

If your app is not yet released:

1. Uninstall the app from device.
2. Open a Detour link in a mobile browser.
3. Store redirect may fail if the store app page is not public yet.
4. Install your development build.
5. Launch app and verify link is resolved within matching window (currently 15 minutes).

Testing Android

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

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

For local install referrer testing workarounds, see: https://medium.com/@madicdjordje/how-to-test-the-play-store-install-referrer-api-78a63d59945b

If you encounter click_id missing in your build see limitations section Play Store referrer missing

Testing Android App Links

When app is already installed, link opening depends on certificate fingerprint configured in dashboard:

Installation method	SHA-256 to configure
Direct .apk from EAS	EAS fingerprint
Google Play Internal Testing	Play App Signing key
Local development (npx expo run:android)	Local debug keystore

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
• Universal/App link not delivered, [Detour:CLICK_LIMIT_ERROR] in logs
  • your app exceeded its click limit for the current period — check your plan's limits in Billing & Payments
  • the dedicated CLICK_LIMIT_ERROR is emitted only for Universal/App links; deferred and short links share the same plan limits but over-limit just makes them fail to resolve (return null, no dedicated error), and custom scheme links are not limit-checked
  • a temporary network/backend error never blocks a link (the check fails open)
• 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). 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
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.