# API Reference

## DetourProvider

Top-level React component that initializes the Detour SDK for deferred link matching. It manages the matching lifecycle and exposes the result via React context.

On mount, the provider:

1. Checks if this is the first app entrance using persisted state in AsyncStorage
2. If first entrance, collects a device fingerprint and queries the Detour API for a matching deferred link
3. On Android, attempts deterministic matching using the install referrer `click_id` before falling back to probabilistic fingerprinting
4. Updates context state with the result via [`useDetourContext()`](#usedetourcontext)

Use exactly one `DetourProvider` at the root of your app tree. The matching logic runs only once per app install, and subsequent app opens skip the API call entirely.

### 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>
</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 deferred link matching state from the nearest `DetourProvider`. Throws an error if called outside of a `DetourProvider` tree.

### Signature

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

### Returned object

<PropertyList>
  <Property name="deferredLinkProcessed" type={"boolean"}>
    `true` once the SDK has finished the deferred link matching attempt, 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. `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;
};
```

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

### DeferredLinkContext

```ts
type DeferredLinkContext = {
  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>