React Native Referral Program: Invite Links and Rewards

To build a referral program in React Native, mark a link as a referral link, let the new person open it, and call two SDK methods: redeemInvitation on iPhone and claimReferral at sign-up. The SDK matches the install to the sharing link. A signed webhook then tells your server to grant the reward.

This guide uses @warplink/react-native 1.2.0 and covers bare React Native and Expo. The reference version lives in the React Native referral quickstart.

How a React Native referral works

A friend shares an invite link. The new person taps it, installs the app, opens it, and signs up. Your app needs to know which link brought them. The two platforms differ:

• Android. Google Play stores the invitation in the install referrer, and the SDK reads it at first launch. The match is exact (android_referrer) and shows no screen. Android install referrer referral code in Kotlin shows what happens underneath.
• iPhone. An App Store install carries no data. The invite page puts the invitation on the clipboard, and your app asks the person to paste it. The match is exact (install_token). Make a referral link survive the App Store on iPhone explains the iPhone side.

Both end in the same call, claimReferral, so the rest of your code is one path.

Install the SDK

For bare React Native:

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

The iOS SDK needs dynamic linkage. Add use_frameworks! :linkage => :dynamic to ios/Podfile before pod install.

For Expo:

npx expo install @warplink/react-native
npx expo prebuild

SDK 1.1.x cannot read an invitation, so check the installed version is 1.2.0 or later. React Native 0.75 and React 18 are the minimums.

Expo

The referral flow works in an Expo development build or a prebuild. It does not run in Expo Go, because redeemInvitation and claimReferral call into native code that Expo Go does not contain. Install the package, then run npx expo prebuild, which generates the native projects. The usual native steps apply, such as dynamic linkage on iOS. Build a development client with EAS Build or run the prebuild locally, then test on a real phone.

The Expo setup notes list the build steps, and Expo deferred deep linking walks through the same build for deferred links.

Create a referral link

Any link that belongs to an app can be a referral link. Turn on Referral link in the dashboard, or send is_referral over REST:

curl -X POST https://api.warplink.app/v1/links \
  -H "Authorization: Bearer wl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "slug": "invite-ana",
    "destination_url": "https://example.com/invite",
    "is_referral": true
  }'

Store the returned link id with the user who shares it. The webhook names that link later, and the id tells you whose invitation earned the credit.

Configure the SDK once

Call configure at module level, outside any component, so it runs once per launch:

import { WarpLink } from '@warplink/react-native';

WarpLink.configure({
  apiKey: 'wl_live_yoursdkkeyhere000000000000000000',
  debugLogging: __DEV__,
  onLink: ({ deepLink, error }) => {
    if (error) return;
    if (deepLink?.isDeferred) showWelcomeFromInvitation(deepLink);
  },
});

On Android, the referrer match arrives in onLink like any other deferred link.

Redeem the invitation on iPhone

The React Native package has no paste button component. The SDK never reads the clipboard itself, and it sees only the text you pass in. Show a text input on your first screen, ask the person to paste the invitation, and pass the text to redeemInvitation:

import { useState } from 'react';
import { Button, TextInput, View } from 'react-native';
import { WarpLink } from '@warplink/react-native';

export function InvitePaste({ onDone }: { onDone: () => void }) {
  const [text, setText] = useState('');

  async function apply() {
    try {
      const link = await WarpLink.redeemInvitation(text);
      if (link) showApplied(); // null: not an invitation, or no match
    } catch (error) {
      showMessage((error as Error).message); // says how to open the link again
    }
    onDone();
  }

  return (
    <View>
      <TextInput
        value={text}
        onChangeText={setText}
        placeholder="Paste your invitation"
        multiline
      />
      <Button title="Apply" onPress={apply} />
      <Button title="Skip" onPress={onDone} />
    </View>
  );
}

Two rules keep this honest. The paste step is an offer, not a gate, so keep the skip button and let onboarding continue when redeemInvitation returns null or throws. And do not read the clipboard in the background to fill the field: iOS asks the person to allow a paste your app starts, and the person should see why.

If the app should offer a clipboard prompt of its own, make the person tap a button first, then read the clipboard with a library you choose and pass the text on. That keeps the read tied to a visible tap.

A refused invitation rejects with a WarpLinkError whose code is E_SERVER_ERROR. After a network failure, the native SDK keeps the invitation and tries again on a later launch. That later result arrives through getAttributionResult() and claimReferral, not onLink.

Claim the install at sign-up

When the new person signs up, call claimReferral with an installer id: a dedicated random id for that user, 1 to 128 characters. Do not use a primary key, an email address, or a phone number.

import { WarpLink, type ReferralClaimResult } from '@warplink/react-native';

async function claimForNewUser(installerId: string): Promise<ReferralClaimResult | null> {
  try {
    return await WarpLink.claimReferral(installerId);
  } catch (error) {
    // E_NETWORK_ERROR, E_INVALID_API_KEY, E_NOT_CONFIGURED, or E_SERVER_ERROR
    // for an empty or too long installer id.
    reportError(error);
    return null;
  }
}

claimReferral is safe to repeat. The first valid claim for an app and installer id wins, and the same call again returns the same claim. Handle each status:

const claim = await claimForNewUser(user.warplinkId);
switch (claim?.status) {
  case 'claimed':
    break; // credited inside the window
  case 'flagged':
    break; // credited after the window: claim.flags has "outside_window"
  case 'ignored':
    break; // already credited: see claim.duplicateOf
  case 'none':
    break; // no referral link brought this install
}

none is an ordinary answer, not an error. The result also carries referralId, linkId, matchMethod, isExact, matchConfidence, flags and duplicateOf.

Grant the reward from the webhook

Your server receives a signed referral.claimed event within seconds of the claim. Verify the signature on the raw body, skip an event id you have already seen, then grant the reward from your own rules:

if (event.type === 'referral.claimed') {
  await grantReward({
    inviterLinkId: event.data.link.id,
    newUserId: event.data.installer_id,
    exact: event.data.match.exact,
  });
}

The reward itself stays in your system. Receive a referral reward webhook in Node.js shows the receiver, and Verify a referral before you grant the reward lists the checks to run first. For rewards of value, claim from your backend with POST /v1/referrals/claims and let your own rules decide when a sign-up has earned one.

If the reward is store credit or a subscription month, read App Store and Google Play referral reward rules first.

Test it

Test on a real phone with a development build, not Expo Go. On Android, install from a Google Play internal testing track. On iPhone, install from TestFlight or the App Store, then paste the invitation. How to test the install referrer and referral links has the full steps, the webhook test, and the Referrals report checks.

Frequently Asked Questions

How do I add a referral program to a React Native app?

Install @warplink/react-native 1.2.0, mark a link as a referral link, call redeemInvitation on iPhone, and call claimReferral when the new person signs up. A signed webhook then tells your server to grant the reward.

Does the React Native referral flow work in Expo Go?

No. redeemInvitation and claimReferral are native module calls, so the flow needs an Expo development build or a prebuild. Install the package, then run npx expo prebuild or build with EAS Build. The Expo notes in the SDK setup guide cover the rest.

Do I need a paste step on Android in React Native?

No. Google Play carries the invitation in the install referrer and the SDK matches it on first launch. Only iPhone needs the person to paste the invitation, because an iOS install carries no data.

How do I get a system paste button in React Native?

The React Native package has no paste button component. Use a plain text input where the person pastes the invitation, or a clipboard prompt your app owns. The SDK never reads the clipboard and sees only the text you pass in.

How do I stop one person claiming the same reward twice?

Pass the same installer id for the same user. The first valid claim for an app and installer id wins, and a later claim returns status ignored with a duplicateOf reference.

Related Guides

• Quickstart: React Native referral quickstart and the full referrals guide.
• Other platforms: Android install referrer referral code, Flutter referral system, and referral links on iPhone.
• Test it: How to test the install referrer and referral links.
• React Native deep links: React Native deep linking and deferred deep linking in React Native.
• Choosing an approach: Best ways to add a referral program to a mobile app.

How WarpLink Helps

One SDK covers both stores. The same two calls work on Android and iPhone, the match is exact on both, and every claim shows in the Referrals report with its webhook deliveries. The reward and its rules stay in your system.

One workflow, three pillars. Deep linking carries the invitation, install attribution credits the link that produced the new user, and real-time analytics shows referrals beside every other link. Sub-10ms redirects on the way in, one SDK on the way out.

Create a free WarpLink account and get deep linking, install attribution, and real-time analytics in one SDK, with 10,000 clicks a month on the free plan.