@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

📦 Installation

npm install @oneclub/deeplink

or for local dev:

npm install ../oneclubsdk

🧠 Quick Usage

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:

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:

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:

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:

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:

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:

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:

import DeferredLinkFetcher from "@oneclub/deeplink";

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

🧪 Examples

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