@deeplinx/react-native

Official React Native SDK for DeepLinx - Smart Deep Linking Platform.

Features

• 🔗 Deferred Deep Linking - Capture context through app install
• 📊 Event Tracking - Track custom events and conversions
• 👤 User Identification - Link anonymous users to accounts
• 🔒 Install Attribution - Track which links drive installs
• ⚛️ React Hooks - Easy integration with functional components
• 📱 Native Integration - Works with iOS and Android

Installation

npm install @deeplinx/react-native
# or
yarn add @deeplinx/react-native

Peer Dependencies

npm install @react-native-async-storage/async-storage

Quick Start

1. Wrap Your App with Provider

import { DeepLinxProvider } from '@deeplinx/react-native';

function App() {
  return (
    <DeepLinxProvider
      config={{
        apiKey: 'your-api-key',
        debug: __DEV__,
        onDeepLink: (context) => {
          // Called when deferred deep link is found
          console.log('Deep link received:', context);
          // Navigate to the intended screen
          navigation.navigate(context.context.screen, context.context.params);
        },
      }}
    >
      <NavigationContainer>
        <AppNavigator />
      </NavigationContainer>
    </DeepLinxProvider>
  );
}

2. Use Hooks in Components

import { useDeepLinx, useTrack, useIdentify } from '@deeplinx/react-native';

function HomeScreen() {
  const { deferredContext, isLoading } = useDeepLinx();
  const track = useTrack();
  const identifyUser = useIdentify();

  useEffect(() => {
    if (deferredContext) {
      // User came from a DeepLinx link
      console.log('Referred from:', deferredContext.slug);
    }
  }, [deferredContext]);

  const handleSignUp = async (user) => {
    // Identify the user
    identifyUser(user.id, {
      email: user.email,
      name: user.name,
    });

    // Track the event
    track('sign_up', { method: 'email' });
  };

  return <SignUpForm onSubmit={handleSignUp} />;
}

API Reference

DeepLinxProvider

Wrap your app with this provider to enable DeepLinx functionality.

<DeepLinxProvider
  config={{
    apiKey: string;          // Required: Your API key
    baseUrl?: string;        // Optional: Custom API URL
    debug?: boolean;         // Optional: Enable logging
    onDeepLink?: (ctx) => void; // Optional: Callback for deep links
  }}
  autoMatch?: boolean;       // Optional: Auto-check on mount (default: true)
>
  {children}
</DeepLinxProvider>

useDeepLinx()

Main hook providing access to all DeepLinx functionality.

const {
  isReady,           // boolean: SDK initialized
  isLoading,         // boolean: Currently matching
  deferredContext,   // DeferredContext | null: Matched context
  error,             // Error | null: Initialization error
  track,             // (event, properties?) => Promise<void>
  identify,          // (userId, traits?) => Promise<void>
  getUserId,         // () => string | null
  getAnonymousId,    // () => string
  clearDeferredContext, // () => void
  reset,             // () => void
} = useDeepLinx();

useDeepLinkHandler(handler)

Call a function when deferred context becomes available.

import { useDeepLinkHandler } from '@deeplinx/react-native';

function App() {
  useDeepLinkHandler((context) => {
    // Navigate to the original destination
    navigation.navigate(context.context.screen);
  });
}

useScreenTracking(screenName, properties?)

Track screen views automatically.

import { useScreenTracking } from '@deeplinx/react-native';

function ProductScreen({ route }) {
  useScreenTracking('Product Screen', {
    productId: route.params.productId,
  });

  return <ProductDetails />;
}

useTrack()

Get a memoized track function.

import { useTrack } from '@deeplinx/react-native';

function CheckoutButton() {
  const track = useTrack();

  return (
    <Button
      onPress={() => {
        track('checkout_started', { cartValue: 199.99 });
      }}
      title="Checkout"
    />
  );
}

useIdentify()

Get a memoized identify function.

import { useIdentify } from '@deeplinx/react-native';

function LoginScreen() {
  const identify = useIdentify();

  const handleLogin = async (user) => {
    identify(user.id, { email: user.email });
  };
}

TypeScript Support

Full TypeScript support with exported types:

import type {
  DeepLinxConfig,
  DeferredContext,
  TrackEventProperties,
  UserTraits,
} from '@deeplinx/react-native';

Deferred Context Shape

interface DeferredContext {
  linkId: string;       // The matched link ID
  slug: string;         // Short link slug
  longUrl: string;      // Original destination URL
  context: object;      // Custom data from the link
  iosUrl?: string;      // iOS app scheme URL
  androidUrl?: string;  // Android app scheme URL
  matchedAt: string;    // When the match occurred
  timeSinceClick: number; // Seconds since original click
}

Best Practices

1. Handle Deep Links Early

// In your root navigator
useDeepLinkHandler((context) => {
  // Navigate immediately when context is available
  if (context.context.screen) {
    navigation.navigate(context.context.screen, context.context.params);
  }
});

2. Track Important Events

// Conversion events
track('purchase', { amount: 99.99, productId: 'sku-123' });
track('subscription_started', { plan: 'premium' });
track('referral_sent', { inviteCode: 'ABC123' });

// Engagement events
track('content_viewed', { contentId: 'article-1' });
track('search', { query: 'shoes' });

3. Reset on Logout

const { reset } = useDeepLinx();

const handleLogout = async () => {
  await authService.logout();
  reset(); // Clear DeepLinx state
  navigation.navigate('Login');
};

Troubleshooting

Deep links not matching

1. Ensure your API key is correct
2. Check that autoMatch is true (default)
3. Verify the app was opened within the matching window (default: 24 hours)

AsyncStorage errors

Make sure you've installed the peer dependency:

npm install @react-native-async-storage/async-storage
cd ios && pod install  # iOS only

License

MIT © DeepLinx