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:

Attaches a runtime listener for Universal Links (iOS) / App Links (Android) received while the app is running
Checks for an initial URL that launched the app (Universal/App Link on cold start)
If no initial link is found, checks if this is the first app entrance and queries the Detour API for a matching deferred link
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, and 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

API_KEY required: Type string; Publishable API key from the Detour Dashboard. Used as a Bearer token for API calls.
appID required: Type string; Unique app identifier from the Detour Dashboard. Used to route matching requests to the correct app.
shouldUseClipboard: Type boolean Default 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: Type DetourStorage Default 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

deferredLinkProcessed: Type 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: Type 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: Type 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.

deferredLinkProcessed: Type boolean; true once the SDK has finished all link detection attempts. false during cold start processing.
deferredLink: Type string | URL | null; Matched link data or null if no match found.
route: Type 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).