Linkkit
Dashboard

React Native

How to Add the Linkkit React Native SDK to Your React Native Project

Prerequisites

Before getting started, make sure you have the following:

  • Obtain your publishable key (LINKKIT_PUBLISHABLE_KEY) from your workspace’s Tracking Settings page.
  • Keep your custom domain (LINKKIT_DOMAIN) ready for configuration.
  • (Optional) If you plan to track conversions, make sure conversion tracking is enabled for your links.

Quick Start

This quick-start guide will walk you through the steps to integrate the Linkkit React Native SDK into your React Native application.


1. Install the Linkkit React Native SDK

# With npm
npm install @linkkit/react-native

# With yarn
yarn add @linkkit/react-native

# With pnpm
pnpm add @linkkit/react-native


2. Initialize the SDK

Before using the Linkkit instance, you must initialize the SDK by calling init with your publishable key and domain.

Linkkit provides two ways to initialize the SDK:


Option 1: Use the Linkkit Provider to Wrap Your App

You can initialize the SDK by wrapping your application with the LinkkitProvider component. This makes the Linkkit instance available throughout your app.

import { LinkKitProvider } from "@linkkit/react-native";

export default function App() {
  return (
    <LinkKitProvider
      publishableKey="<LINKKIT_PUBLISHABLE_KEY>"
      linkkitDomain="<LINKKIT_DOMAIN>"
    >
      // Your app content...
    </LinkKitProvider>
  );
}

Option 2: Manually initialize the Linkkit SDK

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

export default function App() {
  useEffect(() => {
    linkkit.init({
      publishableKey: "<LINKKIT_PUBLISHABLE_KEY>",
      domain: "<LINKKIT_DOMAIN>",
    });
  }, []);

  // Return your app...
}



3. Track Deep Link Open Events

Use the trackOpen method on the Linkkit instance to track deep link and deferred deep link open events.

The trackOpen function should be called:

  • Once on the app's first launch without providing a deepLink parameter.
  • Again whenever the app is opened through a deep link, passing the deepLink parameter with the incoming URL.

This helps Linkkit accurately identify app opens and attribute user activity to the correct referral link.

iOS URL Handler Configuration
If your iOS app uses third-party SDKs that handle URLs (such as Facebook/Meta SDK), avoid using || in your AppDelegate’s openURL: handler. If a third-party SDK returns YES first, RCTLinkingManager may not execute and trackOpen will not be triggered. Refer to the troubleshooting guide for details and the recommended fix.
import { useState, useEffect, useRef } from "react";
import { Linking } from "react-native";
import AsyncStorage from "@react-native-async-storage/async-storage";
import linkkit from "@linkkit/react-native";

export default function App() {
  useEffect(() => {
    linkkit.init({
      publishableKey: "<LINKKIT_PUBLISHABLE_KEY>",
      domain: "<LINKKIT_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 linkkit.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 the trackLead method on the Linkkit instance and provide the customer’s external ID, name, and email.

This allows Linkkit to identify the customer and associate future conversion events with the correct user and referral source.

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

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


5. Track Sale Events (Optional)

To track sale events, call the trackSale method on the Linkkit instance and provide the customer’s user ID along with the purchase information.

This enables Linkkit to record completed transactions, attribute revenue to the correct referral source, and provide accurate conversion tracking.

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

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


Examples

Here is an open-source code example you can use as a reference:

React Native
View the complete example on GitHub.