# 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()`](#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

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

### Config fields

<PropertyList>
  <Property name="API_KEY" type={"string"} required>
    Publishable API key from the Detour Dashboard. Used as a Bearer token for API calls (deferred link matching, short-link resolution, analytics)
  </Property>
  <Property name="appID" type={"string"} required>
    Unique app identifier from the Detour Dashboard. Used to route requests to the correct app.
  </Property>
  <Property name="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.
  </Property>
  <Property name="storage" type={"DetourStorage"} typeHref="#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.
  </Property>
</PropertyList>

### 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

```ts
function useDetourContext(): DetourContextType;
```

### Returned object

<PropertyList>
  <Property name="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.
  </Property>
  <Property name="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.
  </Property>
  <Property name="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.
  </Property>
  <Property name="linkType" type={"LinkType | null"}>
    How the link arrived in the app. See [LinkType](#linktype) for values. `null` if no link was found.
  </Property>
  <Property name="clearLink" type={"() => void"}>
    Resets `linkUrl`, `linkRoute`, and `linkType` to `null`. Call after handling navigation to prevent repeated redirects.
  </Property>
</PropertyList>

## 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`

```ts
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`](#detoureventnames) or a custom string. The optional `data` parameter accepts arbitrary metadata (e.g. `{ itemId: '123', price: 49.99 }`).

## Types

### Config

```ts
type Config = {
  appID: string;
  API_KEY: string;
  shouldUseClipboard?: boolean;
  storage?: DetourStorage;
};
```

Configuration object passed to `DetourProvider`. See [Config fields](#config-fields) for detailed descriptions.

### DetourContextType

```ts
type DetourContextType = {
  isLinkProcessed: boolean;
  linkUrl: string | URL | null;
  linkType: LinkType | null;
  linkRoute: string | null;
  clearLink: () => void;
};
```

Shape of the value returned by [`useDetourContext`](#usedetourcontext).

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

### LinkType

```ts
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

```ts
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` |