Docs / React Native and Expo

React Native and Expo SDK

@referralpanda/react-native gives every user a referral code and a share link, matches a friend who installs from that link, and tells your app about rewards. It is in beta: the calls below may still change before 1.0.

You can show the referral screen you designed in the dashboard, build your own screens on the same calls, or mix the two. Nothing the ready-made screen does is private to it.

1. Install

npx expo install @referralpanda/react-native \
  @react-native-async-storage/async-storage react-native-svg

The SDK is an Expo module with a small native part, so it needs an Expo development build or a store build. It does not run in Expo Go, and apps without Expo are not supported yet.

2. Let share links open your app

Add the plugin with your project's link handle. You find the handle in the dashboard, under Apps: it is the first part of your share links, as in go.referralpanda.com/your-link-handle/CODE. Then add your iOS and Android apps in the dashboard so the link domain knows which app to open.

// app.json
{
  "expo": {
    "plugins": [
      ["@referralpanda/react-native", { "linkHandle": "your-link-handle" }]
    ]
  }
}

3. Configure and sign in

import { ReferralPanda } from '@referralpanda/react-native';

// Once, at app start. A public key (rp_pub_...). Never a secret key.
ReferralPanda.configure({ apiKey: 'rp_pub_live_...' });

// When the user signs in, and at each app start while they are signed in.
await ReferralPanda.logIn(user.id);

// After a new account is created.
ReferralPanda.track('signed_up');

// When the user signs out.
await ReferralPanda.logOut();

A share link opened before the user has an account is kept on the device and sent when you call logIn, so the friend is matched without typing a code. On Android the SDK also reads the Play Install Referrer, which survives an install from the store. If you use RevenueCat and its app user id differs from yours, pass { revenueCatAppUserId } to logIn so purchases match the right user.

4a. Show the screen you designed

import {
  ReferralView,
  ReferralScreenHost,
  presentReferralScreen,
} from '@referralpanda/react-native/ui';

// Inline, anywhere in your app:
<ReferralView placement="settings_referral" />

// Or as a sheet over the app. Mount the host once near the root:
<ReferralScreenHost>
  <App />
</ReferralScreenHost>

presentReferralScreen('settings_referral');

Publishing a new version in the dashboard changes the screen in your app within a minute, with no release. See Screens for what a screen can contain. Two parts are opt-in, one import line each, in an app that has the library installed:

// Animations uploaded in the dashboard (needs lottie-react-native)
import '@referralpanda/react-native/lottie';

// Tap to copy, straight to the clipboard (needs expo-clipboard)
import '@referralpanda/react-native/expo-clipboard';

Without them the screen still works: an animation leaves its space empty, and tapping the code opens the share sheet, which has Copy in it.

4b. Or build your own

import { ReferralPanda, useReferral } from '@referralpanda/react-native';

function InviteScreen() {
  const { referral, loading } = useReferral();
  if (loading || !referral) return null;

  return (
    <>
      <Text>Your code: {referral.code}</Text>
      <Text>{referral.stats.total} friends invited</Text>
      <Button
        title="Invite a friend"
        onPress={() => ReferralPanda.share({ message: 'Join me with {{referral.code}}' })}
      />
      {referral.rewards.map((reward) => (
        <Text key={reward.id}>{reward.label}: {reward.state}</Text>
      ))}
    </>
  );
}

`getReferral() / useReferral()`	Code, link, counts, rewards, the program and who invited the user
`getShareContent({ channel, message })`	The link and a message, for your own share flow
`share({ channel, message })`	Opens the system share sheet and records the share
`trackShare(channel)`	Records a share your app handled itself
`redeemCode(code)`	For a code the user types in
`getRewards() / getOfferCode()`	Rewards, and the offer code to redeem in the store
`presentOfferCodeRedemption()`	iOS: opens Apple's own offer code sheet
`getPlacement(key) / usePlacement(key)`	The screen from the dashboard, as data you can render
`getScreenPreview(token)`	A draft from the dashboard, from a Preview on device code. Needs no API key
`track(event, properties)`	Records an event. signed_up moves a referral forward
`addListener(event, fn)`	rewardEarned, rewardUpdated, referralStatusChanged, referralChanged, placementUpdated
`handleURL(url)`	Tells the SDK about a link the app was opened with. Automatic by default

Hear about rewards

const stop = ReferralPanda.addListener('rewardEarned', (reward) => {
  showToast(`You earned ${reward.label}`);
});
// later
stop();

The SDK compares each fresh answer from the server with the last one, so listeners fire the next time your app asks, for example when the user opens the referral screen. To grant a reward on your server the moment it is issued, use Webhooks.

Offline and retries

Screens and the referral summary are saved on the device and returned, marked stale, when the device is offline. Events are queued and sent later. Every write carries an idempotency key, so a retry is never counted twice.

Store rules

A referral code never unlocks paid features by itself. On iOS, a reward that is an offer code is redeemed through Apple's own sheet. The SDK does not read the clipboard, collect advertising ids or fingerprint the device.

Errors

Calls reject with a ReferralPandaError. error.code says why, for example not_logged_in, network_error or rate_limited, and error.requestId identifies the request when you contact support.