API Reference

DetourProvider

Top-level React component that initializes the Detour SDK for deferred link matching and Universal/App Link handling. It manages the link processing lifecycle and exposes the result via React context.

On mount, the provider:

1. Attaches a runtime listener for Universal Links (iOS) / App Links (Android) received while the app is running
2. Checks for an initial URL that launched the app (Universal/App Link on cold start)
3. If no initial link is found, checks if this is the first app entrance and queries the Detour API for a matching deferred link
4. Updates context state with the result via useDetourContext()

Use exactly one DetourProvider at the root of your app tree. The deferred link matching runs only once per app install — subsequent app opens skip the API call entirely. Universal/App Links are handled on every app open.

Signature

function DetourProvider(props: {
  config: Config;
  children: React.ReactNode;
}): JSX.Element;

Config fields

Field	Type	Required	Default	Description
API_KEY	string	Yes	—	Publishable API key from the Detour dashboard. Used as a Bearer token for API calls
appID	string	Yes	—	Unique app identifier from the Detour dashboard. Used to route matching requests to the correct app
shouldUseClipboard	boolean	No	true	iOS only. When true, the SDK reads the device clipboard and includes it in the probabilistic fingerprint for deferred link matching. May trigger the iOS system paste permission prompt. Set to false to skip clipboard access
storage	DetourStorage	No	AsyncStorage	Custom storage adapter for SDK persistence. The SDK stores a first-entrance flag used for deferred link matching. Defaults to @react-native-async-storage/async-storage if installed

Error handling

If the match API returns an error or network calls fail, the provider sets deferredLinkProcessed to true and keeps deferredLink and route as null, allowing your app to continue normally. Errors are logged to the console.

useDetourContext

Hook that returns the current link processing state from the nearest DetourProvider. Throws an error if called outside of a DetourProvider tree.

Signature

function useDetourContext(): DetourContextType;

Returned object

Property	Type	Description
deferredLinkProcessed	boolean	true once the SDK has finished all link detection attempts (deferred link matching and Universal/App Link check), regardless of whether a link was found. Use this to conditionally show a loading/splash screen during cold start
deferredLink	string | URL | null	The matched link — a URL object for full URLs (e.g. https://yourorg.godetour.link/app-hash/promo) or a pathname string. Can be a deferred link or a Universal/App Link. null if no match was found or an error occurred
route	string | null	Normalized in-app route extracted from the matched link. For full URLs, the first path segment (app hash) is stripped and query string is preserved (e.g. /promo/123?utm=1). null if no link was matched

Types

Config

type Config = {
  appID: string;
  API_KEY: string;
  shouldUseClipboard?: boolean;
  storage?: DetourStorage;
};

Configuration object passed to DetourProvider. See Config fields for detailed descriptions.

DetourContextType

type DetourContextType = {
  deferredLinkProcessed: boolean;
  deferredLink: string | URL | null;
  route: string | null;
};

Shape of the value returned by useDetourContext.

Property	Type	Description
deferredLinkProcessed	boolean	true once the SDK has finished all link detection attempts. false during cold start processing
deferredLink	string | URL | null	Matched link data or null if no match found
route	string | null	Extracted in-app route or null. For full URLs, the first path segment (app hash) is stripped

DetourStorage

interface DetourStorage {
  getItem(key: string): Promise<string | null> | string | null;
  setItem(key: string, value: string): Promise<void> | void;
  removeItem?(key: string): Promise<void> | void;
}

Interface for custom storage adapters. The SDK persists a first-entrance flag used for deferred link matching (only triggers on first app install). Methods can be synchronous or asynchronous.

By default, @react-native-async-storage/async-storage is used. Provide a custom adapter if you use a different storage solution (e.g. MMKV, Expo SecureStore).