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:

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 the URL is a short link (single-segment web URL), resolves it to the full destination URL
4. If no initial link is found, checks if this is the first app entrance and queries the Detour API for a matching deferred link
5. Subscribes to analytics events and forwards them to the Detour backend
6. 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 and custom scheme 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 (deferred link matching, short-link resolution, analytics)
appID	string	Yes	—	Unique app identifier from the Detour dashboard. Used to route 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 (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

Property	Type	Description
isLinkProcessed	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	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	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	LinkType | null	How the link arrived in the app. See LinkType for values. null if no link was found
clearLink	() => 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.

Property	Type	Description
isLinkProcessed	boolean	true once the SDK has finished all link detection attempts. false during cold start processing
linkUrl	string | URL | null	Matched link data or null if no match found
linkRoute	string | null	Extracted in-app route or null. For web URLs, the first path segment (app hash) is stripped
linkType	LinkType | null	How the link arrived — 'deferred', 'verified', or 'scheme'. null if no link found
clearLink	() => 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 doesn't 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 — only triggers 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