API Reference

DetourProvider

Top-level React component that initializes the Detour SDK. It manages the full link processing lifecycle: deferred link matching, Universal/App Link listening, custom scheme handling, short-link resolution, and analytics event transport.

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 the URL is a short link (single-segment web URL), resolves it to the full destination URL
If no initial link is found, checks if this is the first app entrance and queries the Detour API for a matching deferred link
Subscribes to analytics events and forwards them to the Detour backend
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 and custom scheme 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 (deferred link matching, short-link resolution, analytics)
appID required: Type string; Unique app identifier from the Detour Dashboard. Used to route 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 (for deferred link matching) and a device ID (for analytics). 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 isLinkProcessed to true and keeps linkUrl, linkRoute, and linkType 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

isLinkProcessed: Type boolean; true once the SDK has finished all link detection attempts, regardless of whether a link was found. Use this to conditionally show a loading/splash screen during cold start.
linkUrl: Type string | URL | null; The matched link, a URL object for full URLs or a pathname string. Can be a deferred link, Universal/App Link, or custom scheme link. null if no match was found or an error occurred.
linkRoute: Type string | null; Normalized in-app route extracted from the matched link. For web URLs, the first path segment (app hash) is stripped and query string is preserved (e.g. /promo/123?utm=1). For custom scheme links, the host and path are combined into a route. null if no link was matched.
linkType: Type LinkType | null; How the link arrived in the app. See LinkType for values. null if no link was found.
clearLink: Type () => void; Resets linkUrl, linkRoute, and linkType to null. Call after handling navigation to prevent repeated redirects.

DetourAnalytics

Analytics module exported from the package root. Requires an active DetourProvider in the component tree. Events are silently dropped if no provider is mounted.

Methods

`logEvent`

DetourAnalytics.logEvent(
  eventName: DetourEventNames | `${DetourEventNames}`,
  data?: any,
): void;

Records a user action or custom event and sends it to the Detour backend. Pass one of the predefined DetourEventNames or a custom string. The optional data parameter accepts arbitrary metadata (e.g. { itemId: '123', price: 49.99 }).

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 = {
  isLinkProcessed: boolean;
  linkUrl: string | URL | null;
  linkType: LinkType | null;
  linkRoute: string | null;
  clearLink: () => void;
};

Shape of the value returned by useDetourContext.

isLinkProcessed: Type boolean; true once the SDK has finished all link detection attempts. false during cold start processing.
linkUrl: Type string | URL | null; Matched link data or null if no match found.
linkRoute: Type string | null; Extracted in-app route or null. For web URLs, the first path segment (app hash) is stripped.
linkType: Type LinkType | null; How the link arrived: 'deferred', 'verified', or 'scheme'. null if no link found.
clearLink: Type () => void; Resets link state to null. Call after navigating to prevent repeated redirects.

LinkType

type LinkType = 'deferred' | 'verified' | 'scheme';

Describes how the link arrived in the app:

Value	Meaning
`'deferred'`	The link was obtained from the Detour deferred-link API. This happens when a user who does not have the app installed clicks a Detour link, installs the app, and opens it. The SDK retrieves the original link from the backend on first launch
`'verified'`	The link arrived as a Universal Link (iOS) or App Link (Android), an HTTP/HTTPS URL that the OS verified belongs to your app and delivered directly to it
`'scheme'`	The link arrived via a custom URL scheme (e.g. `myapp://path`). These are non-HTTP URLs that the OS routes to your app based on the registered scheme

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, which only runs on first app install) and a stable device ID (used for analytics). 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).

DetourEventNames

Category	Event Name	String Value
General	`Login`	`login`
	`Search`	`search`
	`Share`	`share`
	`SignUp`	`sign_up`
	`TutorialBegin`	`tutorial_begin`
	`TutorialComplete`	`tutorial_complete`
	`ReEngage`	`re_engage`
	`Invite`	`invite`
	`OpenedFromPushNotification`	`opened_from_push_notification`
Sales	`AddPaymentInfo`	`add_payment_info`
	`AddShippingInfo`	`add_shipping_info`
	`AddToCart`	`add_to_cart`
	`RemoveFromCart`	`remove_from_cart`
	`Refund`	`refund`
	`ViewItem`	`view_item`
	`BeginCheckout`	`begin_checkout`
	`Purchase`	`purchase`
	`AdImpression`	`ad_impression`