In-App Referrals

Let your app users become referrers from inside your app. With one SDK call you can show a ready-made Refer a friend screen, give each user their own code and link, and see how many friends they have brought in, so you can reward them in your app with credits, tokens or free time.

In-app referrers are normal affiliates. They get a dashboard login, appear in your affiliate list and can earn commission, in-app rewards or both.

How It Works

1. Your app enrols the user. The SDK sends the user's email and name. Insert Affiliate creates their affiliate account, their short code and (for Insert Links companies) their link.
2. The user shares. The drop-in screen shows their code and link with Copy and Share buttons. Sharing uses the phone's own share sheet.
3. Friends are attributed as usual. Installs, events and purchases from the friend's device are attributed to the referrer exactly like any other affiliate.
4. You reward them. The SDK, a webhook and the Public API all report a referral count. When it goes up, grant the reward.

Set Up In Your Dashboard

1. Go to Settings → In-app referrals
2. Turn on Let users become referrers from inside your app
3. Choose What counts as a referral:
   • A friend makes a purchase (recommended): counts new purchases, not renewals
   • A friend completes an in-app event: counts a tracked event such as signup. Enter the event name your app sends.
   • A friend installs the app: counts attributed installs and opens. This is the easiest to fake, see how safe the count is and Store rules.
4. Optionally turn on Require an email code for new referrers if your app doesn't verify email addresses itself
5. Set the Headline, Button colour and Reward text shown on the drop-in screen. The preview updates as you type.
6. Click Save referral settings

Changes to the screen's wording and colour reach your app straight away, with no app release needed.

Add It To Your App

Every SDK has the same methods. The quickest route is the drop-in screen, which handles enrolment, the email code step and sharing for you.

React Native

import { ReferAFriend } from 'insert-affiliate-react-native-sdk';

<ReferAFriend
  visible={showReferral}
  onClose={() => setShowReferral(false)}
  email={currentUser.email}
  name={currentUser.name}
/>

Swift (iOS)

InsertAffiliateSwift.showReferAFriend(
  from: viewController,
  options: ReferAFriendOptions(email: currentUser.email, name: currentUser.name)
)

Flutter, Android (Java/Kotlin), Unity and JavaScript use the same method names. See each SDK's README for its exact syntax: Swift, Android, React Native, Flutter, Unity, JavaScript.

Changing the screen's wording

The screen ships with English text. Your app can replace any label on it with a strings option, passed when it opens the screen. This is how you translate the screen, because we don't ship translations, and how you reword it to sound like your app.

<ReferAFriend
  visible={showReferral}
  onClose={() => setShowReferral(false)}
  strings={{
    emailLabel: 'Correo electrónico',
    joinButton: 'Obtener mi enlace',
    codeSentNotice: 'Enviamos un código de 6 dígitos a {email}.',
    shareButton: 'Compartir',
    premiumUntil: 'Premium gratis hasta {date}',
  }}
/>

Rules for every SDK:

• Override only what you want. A key you leave out, or set to a blank string, keeps our English text. A key we don't know is ignored.
• Keep the placeholders. {email} in codeSentNotice and {date} in premiumUntil are filled in when the text is shown.
• Headline and reward text aren't in strings. They come from your dashboard, and each SDK has its own option to override them per call.

The keys most SDKs share:

Each SDK's screen is a little different, so each README has the full list with our English defaults. The JavaScript SDK splits copyCodeButton and copyLinkButton and has no "Your code" heading, and the Android, Unity, Flutter and React Native SDKs add keys for labels of their own, such as a separate "Your link" title or the placeholder text inside the fields.

An error code we don't have a key for falls back to errorServer.

Styling the screen

The same options object also sets the look, per call:

• Colour: primaryColor, a #RRGGBB value that overrides your dashboard's button colour.
• Font: fontName on Swift, fontFamily on React Native, Flutter and JavaScript, font on Unity, and setTypeface on Android.
• Corner radius: cornerRadius for the buttons, fields and the sheet itself.
• Share text: shareMessage, the message the share sheet starts with.

Building your own screen

Prefer your own design? Skip our screen and call the methods yourself. They are everything the drop-in screen uses.

Call them in this order:

1. getReferralProgramConfig() when your screen opens. If it isn't enabled, don't show the screen.
2. getMyAffiliateDetails() at the same time. Details mean this device is already connected, so go straight to the joined state.
3. Not enrolled: collect an email and name, then call createAffiliateForUser. created goes to the joined state, verificationRequired goes to the code step.
4. Code needed: collect the 6-digit code and call verifyAffiliateCode. To send a new code, call createAffiliateForUser again.
5. Joined: show the short code and link, referralCount, totalEarned and currency, and offer copy and share.
6. Rewards: rewardsGranted and premiumUntil cover free premium time. rewardCodes holds store codes, each with code, store and redeemUrl. Show only the ones for the phone the user is on, because an App Store code can't be redeemed on Android and a Google Play code can't be redeemed on iPhone.
7. Errors: every error comes back as a code, such as PROGRAM_DISABLED, AFFILIATE_LIMIT_REACHED, INVALID_EMAIL, INVALID_CODE, TOO_MANY_CODES or RATE_LIMITED, so you can write your own wording.
8. setReferrerAccount when the user subscribes or signs in later, and signOutAffiliate() when they log out.

Two things to know before you start:

• A missing result doesn't say why. getMyAffiliateDetails() returns nothing both when the device isn't connected and when the request failed. Check isUserAnAffiliate() afterwards to tell them apart: still true means the request failed and is worth retrying.
• A few of the screen's helpers are internal. Filtering reward codes by store, building the share text and tidying up a typed code are not public, so your screen writes its own. They are a couple of lines each over what the methods already return, and shareReferralLink covers the share text.

redeemUrl and dashboardUrl come from our server, so check each one starts with https:// before you open it.

Reinstalls And New Phones

When a user becomes a referrer, their phone gets a private sign-in token that proves who they are. On iPhone it is kept in the Keychain, so it usually survives deleting and reinstalling the app.

If the token is lost (a new phone, or a reinstall on Android), enrolling the same email again doesn't hand over access straight away. Instead:

1. createAffiliateForUser returns verificationRequired and we email the user a 6-digit code
2. The user enters it and your app calls verifyAffiliateCode
3. The phone is connected again. Their referrals, earnings and dashboard are untouched.

The drop-in screen shows this step automatically. Codes expire after 10 minutes and stop working after 5 wrong attempts, and we send at most 3 codes an hour to the same email (after that, createAffiliateForUser returns TOO_MANY_CODES). Anyone who is already your affiliate, including creators with a dashboard, always confirms a code when they connect a new phone. This also stops anyone reading another person's referrals by typing their email.

Rewarding Referrers

Set this up in Settings → In-app referrals → Referrer rewards. It applies to each new referrer who joins from your app:

• Cash commission: your default commission, no cash (rewards only), or a different commission just for referrers.
• Their friend's discount: pick one of your offer codes for iOS, Android and web. Friends who use a referrer's link or code get it.
• Their reward for each referral: Nothing extra (commission only), Free premium time, given automatically, or I'll reward them myself.

referralCount counts each friend once and only ever goes up.

Free premium time, given automatically

We grant the reward through whatever you use for purchases, the moment a referral counts:

Tell us who the referrer is in your purchase system, so we can reward the right account:

// When they join (RevenueCat app user ID or Adapty customer user ID)
await createAffiliateForUser(email, name, { appUserId: revenueCatAppUserId });

// Or later, e.g. once they subscribe (Android: their Play purchase token)
await setReferrerAccount({ appUserId, playPurchaseToken });

If a referral comes in before your app has sent this, the reward waits and is given as soon as it arrives.

On Android, send the referrer's Play purchase token as soon as they subscribe. Without it we can't tell they are a subscriber, so they get a promo code instead, and Google won't let someone who has subscribed before redeem one.

App Store offer codes: we create one-time codes for you with your App Store Connect key. Someone can only redeem one code per offer, so pick your offers in order: a referrer's 2nd reward comes from your 2nd offer, and so on. The offer decides what they get, for example one month free. Each referrer can get one App Store reward per offer you pick (up to 20 offers). Once they've had them all, further rewards show as failed, so pick enough offers or reward the rest yourself.

Google Play promo codes: Google has no way for us to create promo codes, and only people who have never subscribed can redeem one. So subscribers get their bill moved back, and everyone else gets a code from a list you upload:

1. In Play Console, open Monetize with Play > Promo codes and create a promotion of one-time codes for your subscription, with a free trial of 3 to 90 days. Google allows 10,000 codes per subscription each quarter.
2. Download the CSV and upload it in Settings > In-app referrals, with the promotion's end date. We stop handing codes out 2 days before it.
3. Each reward takes the next unused code. If you run out, rewards wait and go out within the hour after your next upload.

Rewarding them yourself

How safe is the count? It depends on what you count:

• Purchases can't be faked. A purchase only counts after it is verified against the store receipt through your purchase verification (App Store, Google Play, RevenueCat, Adapty and the rest), exactly like any affiliate sale. Purchase-based rewards are safe, including free months.
• Signups and installs are reported by your app, so a modified app or scripted calls could fake them. Use them for small perks and count purchases for anything valuable.

For the strongest setup, grant rewards from your server. Your backend reads the verified count through the webhook or the Public API instead of trusting what the phone shows.

Webhook: referral.created

If you have webhooks set up, we send referral.created each time something you count as a referral happens:

{
  "event": "referral.created",
  "affiliate_id": "ia_45fee001",
  "email": "[email protected]",
  "deep_link": "https://myapp.link/ref/abc123",
  "short_code": "a1b2c3d4",
  "trigger": "purchase",
  "referral_count": 3,
  "reward_status": "not_automatic",
  "occurred_at": "2026-09-18T12:00:00.000Z"
}

Reward up to referral_count. Because it's a running total, you never reward twice, and the next delivery catches up any you missed. Webhooks aren't retried, so for a full picture check the Public API, which always shows the current count.

reward_status says what happened to our automatic reward when the referral was recorded:

• granted: given
• not_automatic: we don't give a reward. Either you chose I'll reward them myself, so reward them now, or you chose Nothing extra (commission only).
• waiting_for_account: we don't know the referrer's account in your purchase system yet, or your purchase system doesn't have a record of them yet. We retry every hour, so this clears itself once their account exists.
• waiting_for_codes: we're waiting for Apple to make offer codes, or for you to upload more Google Play promo codes. We retry every hour.
• failed: the reward couldn't be given, for example a key or setting is missing. The most common causes are no App Store Connect key or offers set up (so iPhone referrers can't be rewarded), a missing entitlement or access level name, and a referrer who has already had every offer you configured.
• capped: over the monthly limit, don't reward this one

It is sent once, when the referral is recorded. If a waiting reward is given later, no second webhook is sent.

Public API

GET /public/v1/affiliates/{identifier} (the affiliate's email or short code) includes a referrals object with trigger (what your program counts), referralCount, installCount, eventCount and purchaseCount. The Public API is available on the Enterprise plan.

Self-referrals and limits

• Each friend counts once. Installs and events are matched to the friend's phone, so a friend who signs up twice is one referral. Purchases are matched to the friend's app account (their RevenueCat app user ID or Adapty customer user ID). Without one, each purchase is matched on its own, so a friend who buys two different products can count twice.
• A referral needs a friend we can identify. An install or event that arrives without a device ID isn't counted.
• Referring yourself doesn't count. An install or event from the referrer's own phone is recorded but not counted or rewarded. For purchases, we can only spot the referrer's own purchase when your app has sent their app user ID (see above) and the same ID comes with the purchase. Without it, a referrer who buys on their own phone is counted like any friend.
• Monthly limit (optional). Off by default. Turn on Limit rewards per referrer each month to cap rewards. Referrals past the limit still count towards their total but earn no reward that month.

Program stats

The In-app referrals tab shows your referrers, referrals in total and this month, rewards given, and your top referrers.

Store Rules

Referral programs are allowed on the App Store and Google Play. The drop-in screen follows these rules for you:

• Sharing is optional. Never lock a feature behind sharing, and never reward a rating or review.
• Share sheet only. The screen doesn't ask for access to Contacts and has no "invite everyone" option.
• Reward real actions. Rewarding purchases or in-app events is safest. Google Play watches for apps that reward installs.
• Free premium time. Grant it through App Store offer codes, Google Play promo codes or a moved-back Google Play bill, a RevenueCat promotional entitlement or an Adapty access level, rather than a code system of your own.
• No crypto rewards for inviting people.

Good To Know

• Referrers take a seat. Each one counts towards your plan's affiliate limit, like any affiliate. When you reach the limit, createAffiliateForUser returns AFFILIATE_LIMIT_REACHED.
• An email is required to become a referrer. It is how they sign in to their dashboard.
• Links. Each referrer gets a link the same way as any new affiliate: Insert Links companies get one generated automatically, Short Code Only companies share the code, and Branch, AppsFlyer and RevenueCat Web Purchase Link companies get the next link from their uploaded deep links. If you run out of uploaded links, new referrers still join and share their code, so keep the list topped up.
• Commission. Referrers get the commission you choose under Referrer rewards. Pick No cash (rewards only) if you only want to give in-app rewards.
• Finding them. In-app referrers have an In-app badge in your affiliate list, and you can filter by how affiliates joined.