> ## Documentation Index
> Fetch the complete documentation index at: https://dub.co/llms.txt
> Use this file to discover all available pages before exploring further.

# React Native

> How to add the Dub React Native SDK to your React Native project

## Prerequisites

Before you get started, make sure you have the following:

1. Obtain your [publishable key](/docs/api-reference/authentication#publishable-keys) (`DUB_PUBLISHABLE_KEY`) from your [workspace's Tracking settings page](https://app.dub.co/settings/tracking).
2. You would also want to have your [custom domain](https://app.dub.co/settings/domains) (`DUB_DOMAIN`) handy as well.
3. (Optional) If you plan to track conversions, make sure to [enable conversion tracking for your links](/docs/quickstart/server#step-1-enable-conversion-tracking-for-your-links).

> [!NOTE]
>
> Want to test your app before going live? Use the publishable key from a
> [staging workspace](/docs/testing) to track test events without affecting your
> production analytics.

## Quickstart

This quick start guide will show you how to get started with Dub React Native SDK in your React Native app.

### 1. Install the Dub React Native SDK

```sh theme={null}
# With npm
npm install @dub/react-native

# With yarn
yarn add @dub/react-native

# With pnpm
pnpm add @dub/react-native
```

### 2. Initialize the SDK

You must call `init` on your `dub` instance with your publishable key and domain prior to being able to use the `dub` instance. We provide two ways to initialize the SDK:

**Option 1**: Use the `DubProvider` to wrap your app

```typescript theme={null}
import { DubProvider } from "@dub/react-native";

export default function App() {
  return (
    <DubProvider
      publishableKey="<DUB_PUBLISHABLE_KEY>"
      dubDomain="<DUB_DOMAIN>"
    >
      // Your app content...
    </DubProvider>
  );
}
```

**Option 2**: Manually initialize the Dub SDK

```typescript theme={null}
import dub from "@dub/react-native";

export default function App() {
  useEffect(() => {
    dub.init({
      publishableKey: "<DUB_PUBLISHABLE_KEY>",
      domain: "<DUB_DOMAIN>",
    });
  }, []);

  // Return your app...
}
```

### 3. Track deep link open events

Call `trackOpen` on the `dub` instance to track deep link and deferred deep link open events.
The `trackOpen` function should be called once without a `deepLink` parameter on first launch, and then
again with the `deepLink` parameter whenever the app is opened from a deep link.

> [!WARNING]
>
> If your iOS app uses third-party SDKs that handle URLs (e.g., Facebook/Meta SDK), make sure your `AppDelegate`'s `openURL:` handler doesn't short-circuit with `||`. When a third-party SDK returns `YES` first, `RCTLinkingManager` never fires and `trackOpen` won't be called. See the [troubleshooting guide](/docs/concepts/deep-links/quickstart#troubleshooting-deep-links) for details and a fix.

```typescript React Native expandable theme={null}
import { useState, useEffect, useRef } from "react";
import { Linking } from "react-native";
import AsyncStorage from "@react-native-async-storage/async-storage";
import dub from "@dub/react-native";

export default function App() {
  useEffect(() => {
    dub.init({
      publishableKey: "<DUB_PUBLISHABLE_KEY>",
      domain: "<DUB_DOMAIN>",
    });

    // Check if this is first launch
    const isFirstLaunch = await AsyncStorage.getItem("is_first_launch");

    if (isFirstLaunch === null) {
      await handleFirstLaunch();
      await AsyncStorage.setItem("is_first_launch", "false");
    } else {
      // Handle initial deep link url (Android only)
      const url = await Linking.getInitialURL();

      if (url) {
        await handleDeepLink(url);
      }
    }

    const linkingListener = Linking.addEventListener("url", (event) => {
      handleDeepLink(event.url);
    });

    return () => {
      linkingListener.remove();
    };
  }, []);

  const handleFirstLaunch = async (
    deepLinkUrl?: string | null | undefined
  ): Promise<void> => {
    try {
      const response = await dub.trackOpen(deepLinkUrl);

      const destinationURL = response.link?.url;
      // Navigate to the destination URL
    } catch (error) {
      // Handle error
    }
  };

  // Return your app...
}
```

### 4. Track lead events (optional)

To track lead events, call `trackLead` on the `dub` instance with your customer's external ID, name, and email.

```typescript React Native theme={null}
import dub from "@dub/react-native";

try {
  await dub.trackLead({
    eventName: "User Sign Up",
    customerExternalId: user.id,
    customerName: user.name,
    customerEmail: user.email,
  });
} catch (error) {
  // Handle sale tracking error
}
```

> **Lead event attributes**
>
> Here are the properties you can include when sending a lead event:
>
> | Property | Required | Description |
> | :- | :- | :- |
> | `clickId` | **Yes** | The unique ID of the click that the lead conversion event is attributed to. You can read this value from `dub_id` cookie. If an empty string is provided (i.e. if you're using [tracking a deferred lead event](/docs/conversions/leads/deferred)), Dub will try to find an existing customer with the provided `customerExternalId` and use the `clickId` from the customer if found. |
> | `eventName` | **Yes** | The name of the lead event to track. Can also be used as a unique identifier to associate a given lead event for a customer for a subsequent sale event (via the `leadEventName` prop in `/track/sale`). |
> | `customerExternalId` | **Yes** | The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer. |
> | `customerName` | No | The name of the customer. If not passed, a random name will be generated (e.g. "Big Red Caribou"). |
> | `customerEmail` | No | The email address of the customer. |
> | `customerAvatar` | No | The avatar URL of the customer. |
> | `mode` | No | The mode to use for tracking the lead event. `async` will not block the request; `wait` will block the request until the lead event is fully recorded in Dub; `deferred` will defer the lead event creation to a subsequent request. |
> | `metadata` | No | Additional metadata to be stored with the lead event. Max 10,000 characters. |

### 5. Track sale events (optional)

To track sale events, call `trackSale` on the `dub` instance with your customer's user ID and purchase information.

```typescript React Native theme={null}
import dub from "@dub/react-native";

try {
  await dub.trackSale({
    customerExternalId: user.id,
    amount: product.price.amount,
    currency: "usd",
    eventName: "Purchase",
  });
} catch (error) {
  // Handle sale tracking error
}
```

> **Sale event attributes**
>
> Here are the properties you can include when sending a sale event:
>
> | Property | Required | Description |
> | :- | :- | :- |
> | `customerExternalId` | **Yes** | The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer. |
> | `amount` | **Yes** | The amount of the sale in cents. |
> | `paymentProcessor` | No | The payment processor that processed the sale (e.g. [Stripe](/docs/integrations/stripe), [Shopify](/docs/integrations/stripe)). Defaults to "custom". |
> | `eventName` | No | The name of the event. Defaults to "Purchase". |
> | `invoiceId` | No | The invoice ID of the sale. Can be used as a idempotency key – only one sale event can be recorded for a given invoice ID. |
> | `currency` | No | The currency of the sale. Defaults to "usd". |
> | `metadata` | No | An object containing additional information about the sale. |
> | `clickId` | No | **\[For direct sale tracking]**: The unique ID of the click that the sale conversion event is attributed to. You can read this value from `dub_id` cookie. |
> | `customerName` | No | **\[For direct sale tracking]**: The name of the customer. If not passed, a random name will be generated. |
> | `customerEmail` | No | **\[For direct sale tracking]**: The email address of the customer. |
> | `customerAvatar` | No | **\[For direct sale tracking]**: The avatar URL of the customer. |

## Examples

Here are some open-source code examples that you can reference:

> **[React Native](https://github.com/dubinc/dub-react-native/tree/main/example)**
>
> See the full example on GitHub.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.