React Native

Prerequisites

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

Obtain your publishable key (DUB_PUBLISHABLE_KEY) from your workspace’s Tracking settings page.
You would also want to have your custom domain (DUB_DOMAIN) handy as well.
(Optional) If you plan to track conversions, make sure to enable conversion tracking for your links.

Quickstart

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

Install the Dub React Native SDK

# With npm
npm install @dub/react-native

# With yarn
yarn add @dub/react-native

# With pnpm
pnpm add @dub/react-native

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

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

import dub from "@dub/react-native";

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

  // Return your app...
}

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.

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 for details and a fix.

React Native

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...
}

Track lead events (optional)

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

React Native

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), 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.

Track sale events (optional)

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

React Native

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, Shopify). 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

See the full example on GitHub.

GETTING STARTED

CONCEPTS

INTEGRATIONS

OPEN SOURCE

React Native

Prerequisites

Quickstart

Install the Dub React Native SDK

Initialize the SDK

Track deep link open events

Track lead events (optional)

Track sale events (optional)

Examples

React Native

​Prerequisites

​Quickstart

Install the Dub React Native SDK

Initialize the SDK

Track deep link open events

Track lead events (optional)

Track sale events (optional)

​Examples

React Native

Prerequisites

Quickstart

Examples