API Reference

DetourProvider

Top-level React component that initializes the Detour SDK for deferred link matching. It manages the matching lifecycle and exposes the result via React context.

On mount, the provider:

Checks if this is the first app entrance using persisted state in AsyncStorage
If first entrance, collects a device fingerprint and queries the Detour API for a matching deferred link
On Android, attempts deterministic matching using the install referrer click_id before falling back to probabilistic fingerprinting
Updates context state with the result via useDetourContext()

Use exactly one DetourProvider at the root of your app tree. The matching logic runs only once per app install, and subsequent app opens skip the API call entirely.

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.

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 deferred link matching state from the nearest DetourProvider. Throws an error if called outside of a DetourProvider tree.

Signature

function useDetourContext(): DeferredLinkContext;

Returned object

deferredLinkProcessed: Type boolean; true once the SDK has finished the deferred link matching attempt, 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. 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;
};

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

DeferredLinkContext

type DeferredLinkContext = {
  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.