react-native-redirectly

React Native SDK for Redirectly - Deep-link handling and attribution tracking for your mobile apps.

Features

• 🔀 Deep Link Handling - Automatically capture and process incoming Redirectly links
• 📊 Attribution Tracking - Track app installs and attribute them to link clicks
• 📱 React Native & Expo - Works with both bare React Native and Expo projects
• 🎯 TypeScript - Full TypeScript support with complete type definitions
• 🚀 Pure TypeScript - No native code required, works out of the box

Note: Link management features (create, update, delete links) are currently private and will be available in a future release.

Installation

npm install react-native-redirectly
# or
yarn add react-native-redirectly

Optional: AsyncStorage for Persistent Install Tracking

For persistent install tracking across app restarts, install AsyncStorage:

npm install @react-native-async-storage/async-storage
# or
yarn add @react-native-async-storage/async-storage

Quick Start

import { useEffect } from 'react';
import Redirectly from 'react-native-redirectly';

export function App() {
  useEffect(() => {
    const redirectly = Redirectly.getInstance();

    // Initialize the SDK
    await redirectly.initialize({
      apiKey: 'your-api-key',
      enableDebugLogging: __DEV__,
    });

    // Listen for install attribution
    const installSub = redirectly.onAppInstalled((install) => {
      if (install.matched) {
        console.log('Install attributed to:', install.matchedClick?.slug);
        console.log('Matched link:', install.matchedLink?.target);
      } else {
        console.log('Organic install (no prior link click)');
      }
    });

    // Check if SDK is ready
    if (redirectly.isInitialized) {
      console.log('Redirectly SDK ready');
    }

    return () => {
      installSub.remove();
      redirectly.dispose();
    };
  }, []);

  return <YourApp />;
}

API Reference

Initialization

Redirectly.getInstance()

Returns the singleton instance of the Redirectly SDK.

const redirectly = Redirectly.getInstance();

initialize(config: RedirectlyConfig): Promise<void>

Initializes the SDK. Must be called before using any other methods.

interface RedirectlyConfig {
  apiKey: string;           // Your Redirectly API key
  baseUrl?: string;         // Custom API URL (default: https://redirectly.app)
  enableDebugLogging?: boolean; // Enable console logging (default: false)
}

await redirectly.initialize({
  apiKey: 'your-api-key',
  enableDebugLogging: __DEV__,
});

dispose(): void

Cleans up listeners and resets the SDK state. Call this before reinitializing with different config.

redirectly.dispose();

isInitialized: boolean

Read-only property to check if the SDK has been initialized.

if (redirectly.isInitialized) {
  // SDK is ready
}

Event Subscriptions

onAppInstalled(callback): Subscription

Subscribe to app install attribution events. This fires when the SDK tracks an app install and determines if it was attributed to a prior link click (deferred deep link).

const subscription = redirectly.onAppInstalled((install) => {
  if (install.matched) {
    // User installed after clicking a Redirectly link
    console.log('Attributed install');
    console.log('Matched to:', install.matchedClick?.slug);
    console.log('Link target:', install.matchedLink?.target);
  } else {
    // Organic install (no prior link click)
    console.log('Organic install');
  }
});

// Unsubscribe when done
subscription.remove();

The install object contains:

• id: Unique install identifier
• matched: Whether install was attributed to a link click
• type: 'organic' or 'non-organic'
• username: Username of matched link (if matched)
• slug: Slug of matched link (if matched)
• matchedLink: Full link details (if matched)
• matchedClick: Original click event (if matched)
• processedAt: ISO timestamp when install was processed

Deep Link Configuration

The SDK automatically handles incoming Redirectly deep links. You need to configure your app to receive universal links (iOS) or app links (Android).

iOS (Expo)

Add to your app.json:

{
  "expo": {
    "ios": {
      "associatedDomains": [
        "applinks:yourname.redirectly.app"
      ]
    }
  }
}

iOS (Bare React Native)

1. In Xcode, go to your target's Signing & Capabilities
2. Add Associated Domains capability
3. Add applinks:yourname.redirectly.app

Android (Expo)

Add to your app.json:

{
  "expo": {
    "android": {
      "intentFilters": [
        {
          "action": "VIEW",
          "autoVerify": true,
          "data": [
            {
              "scheme": "https",
              "host": "yourname.redirectly.app",
              "pathPrefix": "/"
            }
          ],
          "category": ["BROWSABLE", "DEFAULT"]
        }
      ]
    }
  }
}

Android (Bare React Native)

Add an intent filter to your AndroidManifest.xml:

<intent-filter android:autoVerify="true">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data
    android:scheme="https"
    android:host="yourname.redirectly.app"
    android:pathPattern=".*" />
</intent-filter>

Types

The SDK exports all TypeScript types for your convenience:

import type {
  RedirectlyConfig,
  RedirectlyAppInstallResponse,
  RedirectlyLinkClick,
  RedirectlyLinkResolution,
  RedirectlyLink,
  RedirectlyTempLink,
  RedirectlyInstallType,
  Subscription,
} from 'react-native-redirectly';

Error Handling

All async methods may throw RedirectlyError:

import { RedirectlyError } from 'react-native-redirectly';

try {
  await redirectly.initialize({
    apiKey: 'your-api-key',
  });
} catch (error) {
  if (error instanceof RedirectlyError) {
    console.log(error.type);       // 'api' | 'network' | 'config' | 'link'
    console.log(error.statusCode); // HTTP status code (for API errors)
    console.log(error.details);    // Additional error details
  }
}

How It Works

1. Initialization: Call initialize() with your API key
2. Deep Link Capture: SDK automatically listens for incoming Redirectly URLs
3. Link Resolution: When a link is clicked, SDK resolves it and emits events
4. Install Tracking: On first launch, SDK tracks the install and checks for attribution
5. Attribution: If user clicked a link before installing, install is attributed to that link

Roadmap

• 🔜 Link management API (create, update, delete links)
• 🔜 Link click event subscriptions
• 🔜 Initial link retrieval for cold starts

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT