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

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

Config (required prop)

config must be provided and includes authentication and behavioral flags. See Types below for the full Config definition.

Fields:

• API_KEY — the secret API key from your Godetour dashboard (string)

• appID — app identifier issued by the platform (string)

• shouldUseClipboard? — optional boolean (default: true)

What the provider does (runtime behaviour)

On mount it initialises the deferred-linking flow. Internally it:

• Ensures matching runs only once per fresh install/first entrance (the SDK uses persisted state + an in-memory guard so remounts don't re-run the logic).

• Reads the Android install referrer (when available) and — if present — will perform deterministic matching using the clickId.

• Otherwise, builds a probabilistic fingerprint (device model, OS version, screen metrics, locale, timezone, user agent, timestamp and optional clipboard value) and posts it to the match endpoint.

• Updates context state with the result (see hooks below).

The provider does network I/O (calls POST /api/link/match-link) — it must receive a valid API_KEY and appID for requests to succeed. If those are missing or invalid, matching will fail.

Key runtime guarantees & notes

• 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. On iOS this can trigger the system paste permission prompt.

• Error handling: If the match API returns an error or network calls fail, provider will set deferredLinkProcessed = true and deferredLink = null so your app can continue. The SDK logs errors to the console for debugging.

useDetourContext()

Signature

export function useDetourContext(): DeferredLinkContext;

Returned object (DeferredLinkContext)

• deferredLinkProcessed: boolean

  true when the SDK has finished the deferred-link check (either success or failure). While false, your app should wait if you need to route the user based on a deferred link.

• deferredLink: string | URL | null

  If a link was matched, this is the raw link returned by the platform. It can be a full URL string (e.g. https://yourorg.godetour.link/promo) or a URL object. If no match was found or an error occurred, it is null.

• route: string | null

  A normalized path (route) extracted from deferredLink when possible. Example values:

  • "/promo/123?utm=1" (a path with querystring)

  • null if nothing matched

Types

Config

export 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;
};

DeferredLinkContext

export type DeferredLinkContext = {
  /**
   * Boolean indicating if the deferred link has been processed.
   * This is useful for conditionally rendering UI components.
   */
  deferredLinkProcessed: boolean;

  /**
   * The deferred link value. This can be a string or a URL object, or null if no link was found.
   */
  deferredLink: string | URL | null;

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