npm package: @growth-rail/react-native
Description: Growth Rail SDK for React Native
Latest version: 2.0.6

# @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

```bash
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.

```tsx
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`:

```objectivec
#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:

```xml
<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:

```tsx
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:

```tsx
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:

```tsx
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.

```tsx
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:

```tsx
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