# API Reference

## DetourProvider

Top-level React component that initializes the Detour SDK for deferred link matching and Universal/App Link handling. It manages the link processing lifecycle and exposes the result via React context.

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 no initial link is found, checks if this is the first app entrance and queries the Detour API for a matching deferred link
4. 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 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.
  </Property>
  <Property name="appID" type={"string"} required>
    Unique app identifier from the Detour Dashboard. Used to route matching 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 used for deferred link matching. 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 `deferredLinkProcessed` to `true` and keeps `deferredLink` and `route` 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="deferredLinkProcessed" type={"boolean"}>
    `true` once the SDK has finished all link detection attempts (deferred link matching and Universal/App Link check), regardless of whether a link was found. Use this to conditionally show a loading/splash screen during cold start.
  </Property>
  <Property name="deferredLink" type={"string | URL | null"}>
    The matched link, a `URL` object for full URLs (e.g. `https://yourorg.godetour.link/app-hash/promo`) or a pathname string. Can be a deferred link or a Universal/App Link. `null` if no match was found or an error occurred.
  </Property>
  <Property name="route" type={"string | null"}>
    Normalized in-app route extracted from the matched link. For full URLs, the first path segment (app hash) is stripped and query string is preserved (e.g. `/promo/123?utm=1`). `null` if no link was matched.
  </Property>
</PropertyList>

## 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 = {
  deferredLinkProcessed: boolean;
  deferredLink: string | URL | null;
  route: string | null;
};
```

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

<PropertyList>
  <Property name="deferredLinkProcessed" type={"boolean"}>
    `true` once the SDK has finished all link detection attempts. `false` during cold start processing.
  </Property>
  <Property name="deferredLink" type={"string | URL | null"}>
    Matched link data or `null` if no match found.
  </Property>
  <Property name="route" type={"string | null"}>
    Extracted in-app route or `null`. For full URLs, the first path segment (app hash) is stripped.
  </Property>
</PropertyList>

### 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 (only triggers on first app install). 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).