@growth-rail/react-native

The GrowthRail React Native SDK provides a seamless way to integrate referral programs into your React Native applications. It handles multi-platform deep linking, user attribution, and displays premium UI components for referral dashboards and banners.

Features

• 🚀 One-Tap Integration: Wrap your app with GrowthRailProvider to get started.
• 🔗 Deep Linking: Built-in support for attribution via standard and deferred deep links.
• 🎨 Premium UI: Ready-made components for Referral Dashboards and Reward Banners.
• 📱 Cross-Platform: Consistent behavior across iOS and Android.
• ⚡ Lightweight: Optimized for performance with minimal dependencies.

Installation

yarn add @growth-rail/react-native @react-native-async-storage/async-storage react-native-play-install-referrer
# or
npm install @growth-rail/react-native @react-native-async-storage/async-storage react-native-play-install-referrer

Note: For iOS, remember to run cd ios && pod install.

Setup

1. Initialize the Provider

Wrap your main application component with GrowthRailProvider. This handles SDK initialization and provides the context for UI components.

import { GrowthRailProvider } from '@growth-rail/react-native';

const App = () => {
  return (
    <GrowthRailProvider 
      projectSecretKey="YOUR_PROJECT_SECRET_KEY"
      userId="USER_UNIQUE_ID" // optional at start
      appearance="dark"     // "light", "dark", or omit for system default
      debug={true}          // Enable verbose console logging
    >
      <YourAppContent />
    </GrowthRailProvider>
  );
};

2. Deep Link Configuration

iOS (AppDelegate.mm)

Ensure your app handles deep links by adding the following to your AppDelegate:

#import <React/RCTLinkingManager.h>

- (BOOL)application:(UIApplication *)application
   openURL:(NSURL *)url
   options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
  return [RCTLinkingManager application:application openURL:url options:options];
}

Android (AndroidManifest.xml)

Add an intent filter for your deep link scheme:

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="your-app-scheme" />
</intent-filter>

User Initialization

If you didn't provide a userId to the provider, or if the user logs in later:

import { useGrowthRail } from '@growth-rail/react-native';

const handleLogin = async (user) => {
  const { initAppUser } = useGrowthRail();
  await initAppUser(user.id);
};

Tracking Reward Events

Attribute successful actions (like purchases or sign-ups) to the referrer:

import { useGrowthRail } from '@growth-rail/react-native';

const onPurchaseComplete = async () => {
  const { trackRewardEvent } = useGrowthRail();
  await trackRewardEvent('purchase_completed');
};

Using the useGrowthRail Hook

For more control and to access loading/error states in your components:

import { useGrowthRail } from '@growth-rail/react-native';

const MyComponent = () => {
  const { 
    initAppUser, 
    trackRewardEvent, 
    showReferralDashboard, 
    isLoading, 
    isUserReady,
    error 
  } = useGrowthRail();

  const handleAction = async () => {
    await trackRewardEvent('custom_action');
  };

  return (
    <View>
      <Button title="Open Referrals" onPress={() => showReferralDashboard()} />
      {isLoading && <ActivityIndicator />}
    </View>
  );
};

Referral Dashboard

Display a beautiful, pre-built dashboard for users to manage their referrals.

import { useGrowthRail } from '@growth-rail/react-native';

const MyProfile = () => {
  const { showReferralDashboard } = useGrowthRail();

  return (
      <Button 
        title="Refer & Earn" 
        onPress={() => showReferralDashboard({ appearance: 'dark' })} 
      />
  );
};

Generating Referral Links Manually

If you need to build a custom UI, you can generate the referral link directly:

import { useGrowthRail } from '@growth-rail/react-native';

const getLink = async () => {
  const { getReferralLink } = useGrowthRail();
  const referralLink = await getReferralLink();
  console.log('Share this link:', referralLink);
};

Theme & Appearance

The SDK supports light and dark modes out of the box.

• System Default: If no appearance is specified, the SDK follows the user's system setting using useColorScheme().
• Global Setting: Set the appearance prop on GrowthRailProvider.
• Manual Override: Pass appearance to showReferralDashboard({ appearance: 'dark' }).

Standard Colors

The SDK uses a premium, neutral color palette designed to fit seamlessly into any application:

• Light: Clean white background with high-contrast Gray 900 text.
• Dark: Deep Gray 900 background with soft Gray 50 text for reduced eye strain and optimal readability.

API Reference

GrowthRailProvider Props

| Prop | Type | Description | | :--- | :--- | :--- | | projectSecretKey | string | Your GrowthRail Project Secret Key. | | userId | string | (Optional) The current user's unique ID. | | appearance | 'light' \| 'dark' | (Optional) Force a specific theme. Defaults to system. | | debug | boolean | (Optional) Enable verbose console logging. | | apiUrl | string | (Optional) Custom API endpoint. |

ReferrerModalOptions

Options passed to showReferralDashboard(options):

• title: string - Override the dashboard title.
• description: string - Override the dashboard description.
• appearance: 'light' \| 'dark' - Override the appearance for this call.
• theme.primaryColor: string - Your brand color (e.g., #2563eb).

useGrowthRail()

Provides access to SDK methods and state:

• initAppUser(userId): Initializes a user in the GrowthRail system.
• trackRewardEvent(eventName): Tracks a reward-eligible event.
• showReferralDashboard(options): Opens the referral dashboard modal.
• hideReferralDashboard(): Closes the referral dashboard modal.
• getReferralLink(): Returns the user's referral link.
• getReferralTrackingId(): Returns the current tracking ID.
• isInitialized: Boolean indicating if the SDK is ready.
• isUserReady: Boolean indicating if the user is initialized.
• isLoading: Boolean indicating if an operation is in progress.
• error: The last error that occurred.

License

MIT