API Reference

DetourProvider

DetourProvider is the top-level React component that initializes the deferred-linking session and exposes context for the rest of your app.

Signature

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

Props

Property	Type	Required	Description
config	Config	Yes	Configuration object containing authentication and behavioral flags. See Config type for details.
children	React.ReactNode	Yes	Your app's component tree.

Config fields

Field	Type	Required	Default	Description
API_KEY	string	Yes	-	The publishable API key from your Detour dashboard
appID	string	Yes	-	App identifier issued by the platform
shouldUseClipboard	boolean	No	true	Whether to check clipboard for deferred links. iOS-only
storage	DetourStorage	No	AsyncStorage	Storage adapter for detecting first run. Should implement interface DetourStorage

Runtime behavior

On mount, DetourProvider initializes the deferred-linking flow. Internally it:

• Ensures single-run matching — Uses persisted state (AsyncStorage) and an in-memory guard so matching runs only once per fresh install/first entrance
• Reads Android install referrer — When available, performs deterministic matching using the clickId
• Builds probabilistic fingerprint — If no referrer is found, collects device model, OS version, screen metrics, locale, timezone, user agent, timestamp, and optional clipboard value
• Posts to match endpoint — Sends fingerprint to POST /api/link/match-link
• Resolves short links — If a web URL has a single path segment, the SDK attempts to resolve it via POST /api/link/resolve-short before computing the route
• Updates context state — Provides result via useDetourContext()

The provider performs network I/O and requires valid API_KEY and appID. If these are missing or invalid, matching will fail.

Key runtime guarantees

• Single-run: The SDK is designed to attempt matching only once per install/first-open; it will not call the API repeatedly on every app open.
• First-open semantics: The provider checks persisted state (AsyncStorage) to determine whether the device has already been processed; this avoids duplicate attribution attempts.
• Clipboard: If shouldUseClipboard is true the provider checks the clipboard and includes pastedLink in the fingerprint. This behavior applies exclusively to iOS and may trigger the system's paste permission prompt.
• Error handling: If the match API returns an error or network calls fail, the provider will set isLinkProcessed to true and keep linkUrl, linkRoute, and linkType as null so your app can continue. The SDK logs errors to the console for debugging.

Example

import { DetourProvider } from "@swmansion/react-native-detour";
import { NavigationContainer } from "@react-navigation/native";

function App() {
  return (
    <DetourProvider
      config={{
        API_KEY: "your-api-key",
        appID: "your-app-id",
        shouldUseClipboard: true,
      }}
    >
      <NavigationContainer>{/* Your app navigation */}</NavigationContainer>
    </DetourProvider>
  );
}

---

useDetourContext()

Signature

function useDetourContext(): DetourContextType;

Returns

DetourContextType object with the following properties:

Property	Type	Description
isLinkProcessed	boolean	true when the SDK has finished the deferred-link and universal/app link check (either success or failure). While false, your app should wait if you need to route the user based on a link.
linkUrl	string | URL | null	The raw link returned by the platform if matched. Can be a full URL string (e.g., https://yourorg.godetour.link/app-hash/promo) or a URL object. It can be deferred link, universal/app link or uri-scheme deep link. Returns null if no match was found or an error occurred.
linkRoute	string | null	A normalized path extracted from the deferred link, universal/app link or uri-scheme deep link. Examples: "/promo/123?utm=1" (path with query string) or null if nothing matched.
linkType	LinkType | null	The type of the detected link. Can be 'deferred', 'verified' or 'scheme'. This can be null if no link was found.
clearLink	() => void	Clears the current link context (route/url/type). Call this after you handle a link.

Example

import { useDetourContext } from "@swmansion/react-native-detour";
import { useEffect } from "react";
import { useNavigation } from "@react-navigation/native";

function HomeScreen() {
  const { isLinkProcessed, linkRoute, linkType, linkUrl } = useDetourContext();
  const navigation = useNavigation();

  useEffect(() => {
    if (isLinkProcessed && linkRoute) {
      // Navigate based on the link route
      console.log("Link detected:", linkUrl);
      console.log("Route:", linkRoute);

      // Example: navigate to a specific screen
      if (linkRoute.startsWith("/promo")) {
        navigation.navigate("Promo", { url: linkUrl });
      }
    }
  }, [isLinkProcessed, linkRoute, linkUrl, navigation]);

  if (!isLinkProcessed) {
    return <LoadingScreen />;
  }

  return <YourHomeScreen />;
}

DetourAnalytics

DetourAnalytics is a utility module used to track custom user behaviors and marketing events within your application.

Methods

logEvent()

Emits an analytics event to be captured and sent by the active DetourProvider.

Signature

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

---

Types

Config

type Config = {
  /**
   * Your application ID from the Detour dashboard.
   */
  appID: string;

  /**
   * Your API key from the Detour dashboard.
   */
  API_KEY: string;

  /**
   * Optional: A flag to determine if the provider should check the clipboard for a deferred link.
   * When true, it displays permission alert to user.
   * Defaults to true if not provided.
   */
  shouldUseClipboard?: boolean;

  /**
   * Optional: A custom storage adapter. Defaults to AsyncStorage if not provided.
   */
  storage?: DetourStorage;
};

DetourContextType

type DetourContextType = {
  /**
   * Boolean indicating if the deferred link, Universal/App Link or scheme deep link has been processed.
   * This is useful for conditionally rendering UI components.
   */
  isLinkProcessed: boolean;

  /**
   * The deferred link, Universal/App Link or scheme deep link url. This can be a string or a URL object, or null if no link was found.
   */
  linkUrl: string | URL | null;

  /**
   * The detected route based on the link url, or null if no route was detected.
   */
  linkRoute: string | null;

  /**
   * The type of the detected link. Can be 'deferred', 'verified' or 'scheme'. This can be null if no link was found.
   */
  linkType: LinkType | null;

  /**
   * Clears the current link context (route/url/type). Call this after you handle a link.
   */
  clearLink: () => void;
};

DetourStorage

Your storage adapter should implement the following methods:

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

LinkType

Indicates what type of link was process by SDK.

• Deferred - deferred link matched by Detour API, detected during first run.
• Verified - Universal Link or App Link, detected when app is already installed.
• Scheme - uri-scheme deep link, detected when using url based on custom scheme.

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

DetourEventNames - List od defined events

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