Invitebase | React Native

Add referrals to a React Native or Expo app with @invitebase/react-native and the hooks API

This quickstart takes a React Native app from nothing to a validated test referral: install @invitebase/react-native, identify a user, hand them a referral link, then simulate the friend's side and watch the referral state update reactively through the hooks API. Expo's managed workflow is supported via a config plugin — no ejecting. Everything runs in test mode.

Get your test keys

In the dashboard, go to Developers → API keys and copy your test publishable key (pk_test_…). You will also use your test secret key (sk_test_…) in step 6 to simulate the referred user from your terminal:

export INVITEBASE_SECRET_KEY=sk_test_...

Create a campaign

In Campaigns → New campaign, pick the Paid subscription template — it validates a referral when the referred user starts a paid subscription within 14 days, gated on a subscription_started event with plan: paid. Copy the campaign ID (for example 7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15).

Install the SDK

npx expo install @invitebase/react-native

Add the config plugin so the managed workflow handles native linking, the URL scheme, and Associated Domains for you:

app.json

{
  "expo": {
    "plugins": ["@invitebase/react-native"]
  }
}

Then rebuild your dev client (npx expo prebuild or an EAS build) — the package wraps the native iOS and Android SDKs, so it is not available in Expo Go.

npm install @invitebase/react-native
cd ios && pod install

Autolinking covers both platforms. Deep-link handling integrates with your existing Linking setup.

Config-plugin options and the manual deep-link setup for bare projects are in React Native setup.

Configure and identify

Wrap your app in the provider — it calls configure for you and powers the hooks. The SDK starts an anonymous session immediately; identify merges the anonymous history onto your user after signup.

App.tsx

import { InvitebaseProvider } from '@invitebase/react-native';

export default function App() {
  return (
    <InvitebaseProvider publishableKey="pk_test_...">
      <RootNavigator />
    </InvitebaseProvider>
  );
}

Anywhere below the provider, get the imperative client with useInvitebase() and identify after signup or login:

import { useInvitebase } from '@invitebase/react-native';

function SignupScreen() {
  const invitebase = useInvitebase();

  async function onSignedUp() {
    await invitebase.identify({ id: 'usr_123', email: 'sam@example.com' });
  }
  // …
}

Get a referral link

InviteScreen.tsx

import { Button, Share } from 'react-native';
import { useInvitebase } from '@invitebase/react-native';

function InviteButton() {
  const invitebase = useInvitebase();

  async function invite() {
    const link = await invitebase.getReferralLink('7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15');
    // link.url  → https://mycompany.refr.link/a1b2c3
    // link.code → a1b2c3
    await Share.share({ message: link.url });
  }

  return <Button title="Invite a friend" onPress={invite} />;
}

Inbound attribution rides on the native SDKs underneath: the Play Install Referrer on Android, the clipboard handoff and Universal Links on iOS. The config plugin wires the deep-link plumbing; incoming URLs reach the SDK through invitebase.handleInbound(url), which the provider hooks into Expo Linking automatically. One-time domain association is covered in deep-link attribution.

Play the friend from your terminal. First the signup, carrying the referral code for attribution, then the qualifying event:

curl https://api.invitebase.com/v1/events \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "signup",
    "referred_user_id": "usr_friend_1",
    "referral_code": "a1b2c3"
  }'

curl https://api.invitebase.com/v1/events \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "subscription_started",
    "referred_user_id": "usr_friend_1",
    "properties": { "plan": "paid" }
  }'

You can fire the same events from Developers → Event simulator instead. In the real app, the referred user's device sends the qualifying event with one call on the client from useInvitebase():

invitebase.track('subscription_started', { plan: 'paid' });

Watch it validate

Open the dashboard Overview: both events land in the live feed, and the referral moves signed_up → in_progress → validated under your campaign.

In the app, the hooks re-render your components the moment state changes — no polling:

ReferralStatus.tsx

import { Text } from 'react-native';
import { useTierProgress, useRewards } from '@invitebase/react-native';

export function ReferralStatus() {
  const { progress } = useTierProgress();
  const { rewards } = useRewards();

  const validated = progress?.referrals.validated ?? 0;

  return (
    <Text>
      {validated} validated referrals · {rewards.length} rewards
    </Text>
  );
}

useCampaignInfo() and useTierProgress() round out the reactive surface for building invite screens and progress strips.

What's next

Flutter

Add referrals to a Flutter app with invitebase_flutter.

REST API

Drive the whole loop with cURL — no SDK required.

React Native

On this page