# Quick Start

Integrate your first referral program in under 15 minutes. This guide covers installation, user initialization, referral tracking, and reward delivery.

> **Note:** **Prerequisites:** You need a Growth Rail account and a project created in the dashboard. Grab your **Project Secret** from Settings and configure your **Referral Redirect Link**.

## What You'll Build

By the end of this guide, your app will have a complete referral flow:

1. **Install** — Add SDK packages
2. **Initialize** — Wrap app with provider
3. **Identify** — Register users
4. **Track** — Track reward events
5. **Deliver** — Configure webhooks

### 1. Install the SDK

**React**

```bash
npm install @growth-rail/react @growth-rail/core
```

**React Native**

```bash
npm install @growth-rail/react-native @growth-rail/core
```

**Vanilla JS**

```bash
npm install @growth-rail/core
```

### 2. Initialize the SDK

Add the Growth Rail provider at the root of your application. Pass your **Project Secret** as the `projectSecretKey` prop.

**React**

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

function App() {
  return (
    <GrowthRailProvider
      projectSecretKey={import.meta.env.VITE_GROWTH_RAIL_SECRET}
      userId={currentUser?.id}
      debug={import.meta.env.DEV}
    >
      <YourApp />
    </GrowthRailProvider>
  );
}
```

**Vanilla JS**

```typescript
import { GrowthRail } from '@growth-rail/core';

GrowthRail.init({
  projectSecretKey: process.env.GROWTH_RAIL_SECRET,
  autoPageTrack: true,
  debug: true,
});
```

### 3. Identify users after login

Call `initAppUser()` once the user is authenticated. This creates the user in Growth Rail (if they don't exist), generates a unique **referral code**, and returns a shareable **referral link**.

**React**

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

export function DashboardPage() {
  const { initAppUser } = useGrowthRail();
  const { user } = useAuth();

  useEffect(() => {
    if (user?.id) initAppUser(user.id);
  }, [user?.id]);

  return <div>Welcome to your dashboard</div>;
}
```

**Vanilla JS**

```typescript
await GrowthRail.initAppUser(session.userId);
```

### 4. Track reward events

When a referred user completes a qualifying action (signup, purchase, etc.), track the reward event via the backend REST API (`POST /api/v1/sdk/track-reward-event`) or automatically via native Stripe & RevenueCat webhooks/integrations.

```bash
POST https://api.growthrail.dev/api/v1/sdk/track-reward-event
Header: x-project-secret-key: sk_live_xxx

{
  "newUserId": "user_123",
  "referralTrackingId": "tr_789",
  "eventName": "user_signup",
  "environment": "Production"
}
```

> **Note:** **Automatic detection:** When a user lands on your app via a referral link (`?referralCode=ABC123`), the SDK automatically calls `trackReferral()` and stores the tracking ID in a cookie. You track the reward event from your backend server or integration when the qualifying action occurs.

### 5. Configure a webhook

In the [Growth Rail dashboard](https://app.growthrail.dev/dashboard/your-project-id/integration?tab=webhooks), go to **Integrations → Reward Webhooks** and add your backend URL. When a reward is triggered, Growth Rail POSTs a signed JSON payload to your endpoint.

For webhook payload details, authentication, retry behavior, and event types, see the [Webhooks guide](/guides/webhooks).

## Bonus: Show the Referral UI

Growth Rail comes with a built-in referral sharing UI — a floating trigger button and a modal/drawer with the user's referral link, copy button, and social sharing options. The SDK renders this automatically based on your Campaign settings.

**React**

```tsx
const { showReferralDashboard, showFloatingButton } = useGrowthRail();

showFloatingButton({ position: 'bottom-right' });
<button onClick={() => showReferralDashboard()}>Invite Friends</button>
```

**Vanilla JS**

```typescript
GrowthRail.createTriggerButton({ position: 'bottom-right', displayMode: 'floating' });
GrowthRail.showReferralDashboard();
```

## What's Next

### Project Setup

Configure redirect links, project secrets, and multi-environment strategies.

### Referral Flow

Deep-dive into the full referral lifecycle from link creation to reward delivery.

### Reward Logic

Understand trigger events, eligibility checks, and webhook routing per rule.