npm package: @oneclub/deeplink
Description: A React Native SDK for deep linking + deferred linking — inspired by Branch, but built custom.   Tracks deep links and deferred installs via cookies and fallback pages, and supports:
Latest version: 1.0.7

# @oneclub/deeplink

A React Native SDK for deep linking + deferred linking — inspired by Branch, but built custom.  
Tracks deep links and deferred installs via cookies and fallback pages, and supports:

- ✅ Deep links (via `Linking`)
- ✅ Deferred links (via WebView cookie read)
- ✅ Auto-reset after usage
- ✅ `getLatestReferringParams()`
- ✅ Hybrid `subscribe()` API
- ✅ Fully typed (TypeScript)
- ✅ Drop-in usage for both Expo + React Native CLI

---

![npm](https://img.shields.io/npm/v/@oneclub/deeplink)
![build](https://github.com/OneClubGE/deeplink/actions/workflows/release.yml/badge.svg)
![types](https://img.shields.io/npm/types/@oneclub/deeplink)

---

## 📦 Installation

```bash
npm install @oneclub/deeplink
```

or for local dev:

```bash
npm install ../oneclubsdk
```

---

## 🧠 Quick Usage

```tsx
import { subscribe } from '@oneclub/deeplink';

const { renderer } = subscribe(({ screen, id }) => {
  if (screen === 'referral' && id) {
    navigation.navigate('ReferralScreen', { id });
  }
});

return (
  <>
    <NavigationContainer />
    {renderer}
  </>
);
```

---

## ✨ Features

| Feature                      | Supported |
|-----------------------------|-----------|
| Deep link tracking          | ✅         |
| Deferred install handling   | ✅         |
| Hybrid subscribe API        | ✅         |
| `getLatestReferringParams()`| ✅         |
| Auto-reset after usage      | ✅         |
| Fully typed (TS)            | ✅         |
| React Native compatible     | ✅         |

---

## 🔌 API

### `subscribe(callback): { unsubscribe, renderer }`

Subscribe to all deep + deferred links.

#### Parameters:
- `callback`: A function that receives the resolved deep or deferred link parameters.

#### Returns:
- `unsubscribe`: A function to remove the deep link listener.
- `renderer`: A React component that handles deferred link resolution.

#### Example:

```tsx
import { subscribe } from "@oneclub/deeplink";

const { renderer, unsubscribe } = subscribe((params) => {
  console.log("Resolved params:", params);
});

return <>{renderer}</>;
```

---

### `getLatestReferringParams(): ReferringParams | null`

Get the last known referring link.

#### Example:

```tsx
import { getLatestReferringParams } from "@oneclub/deeplink";

const params = getLatestReferringParams();
console.log("Latest referring params:", params);
```

---

### `<LinkSubscriberRenderer />`

Renders the fallback WebView that reads the cookie set by your redirect server.

#### Example:

```tsx
import { LinkSubscriberRenderer } from "@oneclub/deeplink";

<LinkSubscriberRenderer
  callback={(params) => {
    console.log("Deferred link params:", params);
  }}
/>;
```

---

### `useLinkSubscriber(callback)`

A React hook version of `subscribe()` — only handles deep links.

#### Parameters:
- `callback`: A function that receives the resolved deep link parameters.

#### Example:

```tsx
import { useLinkSubscriber } from "@oneclub/deeplink";

useLinkSubscriber((params) => {
  console.log("Deep link params:", params);
});
```

---

### `useDeferredLink(onLinkResolved: (url: string) => void): JSX.Element | null`

The `useDeferredLink` hook is a utility for handling deferred deep links. It renders a component that resolves deferred links and invokes a callback when a link is resolved.

#### Parameters:
- `onLinkResolved`: A callback function that is invoked when a deferred link is resolved. The resolved URL is passed as an argument.

#### Returns:
- A React component (`JSX.Element`) that handles the deferred link resolution process. Returns `null` after the link is resolved.

#### Example:

```tsx
import { useDeferredLink } from "@oneclub/deeplink";

const deferredLinkRenderer = useDeferredLink((url) => {
  console.log("Deferred link resolved:", url);
});

return <>{deferredLinkRenderer}</>;
```

---

### `DeepLinkProvider`

The `DeepLinkProvider` wraps your app and provides the base URL for deferred link resolution.

#### Props:
- `url`: The base URL for deferred link resolution (e.g., `https://1url.ge/`).

#### Example:

```tsx
import { DeepLinkProvider } from "@oneclub/deeplink";

<DeepLinkProvider url="https://1url.ge/">
  <App />
</DeepLinkProvider>;
```

---

### `DeferredLinkFetcher`

A utility component that uses a `WebView` to resolve deferred links by reading cookies from a redirect server.

#### Props:
- `onLinkResolved`: A callback function that is invoked when a deferred link is resolved.

#### Example:

```tsx
import DeferredLinkFetcher from "@oneclub/deeplink";

<DeferredLinkFetcher
  onLinkResolved={(url) => {
    console.log("Deferred link resolved:", url);
  }}
/>;
```

---

## 🧪 Examples

```tsx
import {
  subscribe,
  getLatestReferringParams,
  useDeferredLink,
  useLinkSubscriber,
  LinkSubscriberRenderer,
  DeepLinkProvider,
} from "@oneclub/deeplink";

useLinkSubscriber((params) => {
  console.log(params); // deep
});

const deferred = useDeferredLink((url) => {
  console.log("Deferred link resolved:", url);
});

const { renderer } = subscribe((params) => {
  console.log(params); // deep or deferred
});

return (
  <DeepLinkProvider url="https://1url.ge/">
    {renderer}
  </DeepLinkProvider>
);
```

---

## 🏗️ Setup for Deferred Links

Your redirect page should:
- Set a cookie like `click_id=device-123` for Android
- Include a fallback to the app store
- On install, your SDK resolves it back via `/api/resolve?deviceId=...`

---

## 📄 File Overview

### `subscribe.tsx`

Handles both deep and deferred links. Provides a `subscribe` function that listens for deep links and renders a component for deferred links.

---

### `DeferredLinkFetcher.tsx`

A utility component that uses a `WebView` to resolve deferred links by reading cookies from a redirect server.

---

### `DeepLinkProvider.tsx`

Provides a React context for the base URL used in deferred link resolution.

---

### `useDeferredLink.tsx`

A React hook that renders a component to resolve deferred links and invokes a callback when a link is resolved.

---

### `useLinkSubscriber.ts`

A React hook that listens for deep links and invokes a callback with the parsed parameters.

---

### `getLatestReferringParams.ts`

A utility function to retrieve the last known referring parameters from the store.

---

## 📄 License

MIT © [OneClub](https://oneclub.app)