Referral deep links: invite links that survive the app install
Why refer-and-earn invites lose the code when a friend installs your app, how a referral deep link carries it through Google Play and the App Store, where to grant the reward, the cases that don't count, and how to test the whole flow.
Refer-and-earn is one of the oldest growth loops in mobile: "Give ₹100, get ₹100". The loop has a weak point that most teams find only after launch. The person who receives the invite usually doesn't have your app. They tap the link, go to the store, install, open the app, and the invite code is gone. Now support gets messages that start with "my friend didn't get the reward", and someone adds a "Have a referral code?" box to the sign-up screen that half the people skip.
A referral deep link fixes this by carrying the code through the install, so the app knows who invited the person on its very first open. This post explains how that works, what to build on your side, and the cases that look like referrals but aren't.
What a referral link has to do
A good invite link does four jobs:
- Open the app for a friend who already has it, on the invite screen.
- Get the app for a friend who doesn't, from the right store for their phone.
- Keep the code through the install, so the first open knows who sent them.
- Tell your server, so the reward is granted by code you control.
Jobs 1 and 2 are a normal deep link. Job 3 is a deferred deep link: a link that is kept while the person installs and handed to the app on its first open. If that's new to you, deferred deep linking explained covers it with diagrams. Job 4 is your backend, and it is where most of the rules live.
Two ways to put a code on a link
One link per user. When someone opens the "Invite friends" screen, your server creates a link for them with the code in the destination, and the app shows it. With Strait, that is one API call with the secret key, from your server:
curl https://strait.link/v1/links \
-H "Authorization: Bearer $SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "slug": "invite-a7k2", "longUrl": "https://shop.example.com/invite?code=FRIEND10" }'For an existing user base, POST /v1/links/batch creates up to 500 links in one call, and each item gets its own result, so re-running an import is safe (REST API reference).
One shared link, a code per person. The same link for everyone, with the code added to the address: https://hilltop.strait.link/invite?code=FRIEND10. This saves creating links, but the code is now in the part of the URL that people edit, copy badly, or strip when they "clean up" a link before sharing.
Per-user links cost one API call per user and give you a clean report per referrer. For most apps that is the better trade.
Whichever you pick, don't use a phone number or an email address as the code. The code sits in a link that people forward to groups. Use a random invite code or your internal user id.
How the code survives the install
The path through the store is different on each platform.
Android: exact. When a friend without your app taps the link, the link server sends them to Google Play with the link attached in the install referrer. After the install, the app reads the referrer, asks the server which link it was, and gets the destination back, code included. The referrer is an official Google Play feature, so nothing is guessed. The developer details, with Kotlin, are in our Play Install Referrer guide.
iPhone: a short-lived match, opt-in. The App Store passes nothing from the tap to the app. Strait saves a short-lived match when the friend taps Get the app, and pairs it with the app's first open within an hour. When two recent taps look alike, it refuses to match either rather than send someone to the wrong invite (How iPhone install matching works). iPhone matching is proven on iPhone simulators but not yet on a real iPhone, so for referrals on iPhone keep a fallback (below).
In both cases your app code sees one event. In React Native:
links.onLink((e) => {
if (e.matched && e.path === '/invite') {
// Also fires on the first open after install (e.kind === 'deferred').
saveInviteCode(e.params.code); // "FRIEND10"
}
});The path and every query parameter on the link survive the install, which is why code arrives intact (Deferred deep linking docs).
Grant the reward on your server, not in the app
The app is the wrong place to decide who gets ₹100. Anything the app decides can be replayed by someone who controls the app. Do this instead:
- The app reads the code from the link event and sends it to your backend with the new account (at sign-up, or with the first order, whatever your rule is).
- Your backend checks the rules: is the code real, is this a new account, has this device or payment method been rewarded before, has the referrer hit a cap.
- Your backend grants both rewards and records why.
Strait doesn't hold credits, pay anyone or score fraud. That stays with you, because only your backend knows what a "real new customer" means for your business.
Your server can also hear about link opens directly. The app.opened webhook carries the link, the tap id, kind (direct or deferred) and isInstall (Webhooks). That lets the backend tell "a friend installed from this invite" apart from "a friend who already had the app tapped it", without trusting the app's word for it.
The cases that look like referrals but aren't
Decide these up front, and write them into your terms:
| Case | What happens | Usual rule |
|---|---|---|
| Friend already has the app | The link opens it directly; no install | Often no reward, or a smaller one |
| Same person, new phone | A new install, but an old account | No reward; check the account, not the install |
| Uninstall and reinstall | A reinstall is a new install, and it can come from a fresh invite tap | Reward accounts, not installs |
| Self-referral | The referrer taps their own link on a second phone | Cap rewards per referrer; check payment methods |
| Friend installs but never opens | Nothing runs, so nothing is reported | Not countable by any link service |
The last row is worth knowing before you compare dashboards. An install that is never opened can't be seen by any SDK, so invite installs will always be lower than the Play Console's count (Analytics: how we count).
Keep a fallback for when the match misses
Even with an exact Android path, some invites will arrive without a code: the friend found the app by searching the store, or tapped on an iPhone where the match didn't hold. Two cheap fallbacks:
- A pre-filled code box. If the link event brought a code, fill it in and lock it. If not, show the box empty.
- "Who invited you?" after sign-up, matched against your user list. Lower conversion, but it catches the rest.
Sharing the invite
For many Indian apps, invites move through WhatsApp, so build the share button for it. WhatsApp's own wa.me format opens WhatsApp with a ready message and lets the person pick a contact (WhatsApp Help Center):
const invite = 'https://hilltop.strait.link/invite-a7k2?utm_source=whatsapp&utm_medium=referral';
const text = `Join me on Hilltop Shoes Shop and get ₹100 off: ${invite}`;
await Linking.openURL(`https://wa.me/?text=${encodeURIComponent(text)}`);Set the link's title, description and image so the chat shows a proper card. The link preview checker shows what WhatsApp will display, and our post on WhatsApp link previews covers the fixes when it shows a bare URL. When a tap loads inside WhatsApp's in-app browser instead of going to the system, the browser can't open the app on its own; on Android Strait spots it and shows a one-tap Open in app page, and you can see the decision in the Will it open my app? simulator.
Referrals as a feature: in preview
Everything above works today with ordinary links. Strait has also built a referral feature that does the bookkeeping for you: a code on each link or on each tap (?strait_ref=CODE), the code returned as referralCode on the first open after install, a referral.converted webhook once per referred install that opens, and a per-code report. It is in preview and not switched on in production yet, and the details may change (Referrals preview docs). Build on the flow above now; the preview fields are additions, not a rewrite.
Testing the invite flow
- App installed: send the invite to a test phone that has the app, tap it in WhatsApp, and check the invite screen opens with the code.
- App not installed, Android: use a build from a Google Play internal testing track (a sideloaded build has no referrer), uninstall, tap, install from Play, open. The first screen should be the invite with the code. The step-by-step version is in Test deep links in React Native.
- Reopen: the app should go to its home screen, not replay the invite.
- Backend: confirm the reward rule ran once, and that a second account on the same phone didn't earn it again.
We ran step 2 on a real Android phone with a Play internal testing build in October 2026, with a coupon link instead of an invite: the first open landed on the coupon screen, the install was recorded with the method install_referrer, and reopening went to the home screen. An invite code travels the same way, as a query parameter on the destination.
Sources and how we checked
- The per-user link call, the batch endpoint, the
app.openedwebhook fields and the deferred match rules are from Strait's link engine code and its REST API, Webhooks and Deferred deep linking docs. - The referral preview (
strait_ref,referralCode,referral.converted) is from the Referrals preview docs. It is not switched on in production. - WhatsApp Help Center, chat links: the
wa.me/?text=format. - The Android result is from our recorded real-phone test with a Google Play internal testing build (October 2026). iPhone install matching has not been tested on a real iPhone yet.