Run an app referral program
An app referral program credits an install and a sign-up to the person who invited the new user. We give each inviter a referral link, match the friend's install to that link, and send your backend a signed referral.claimed webhook. You decide the reward and grant it in your own system.
How it works
Create a referral link per inviter
In the dashboard, the API or an MCP client, create a link for your app and turn on Referral link. Make one for each inviter and store its link id with your user record, so a later claim points back to a person.
Set the handoff and the credit window
Open the app's Referral handoff tab and choose the credit window: 24 hours, 7 days or 30 days. Turn on Offer referral handoff on iOS, so a visitor without the app sees an invitation page before the App Store.
Read the invitation at first launch
Android reads the invitation from the Play install referrer, with no screen of yours. On iPhone, show WarpLinkPasteButton on the first screen. React Native and Flutter call redeemInvitation with the pasted text.
Claim the referral after sign-up
Once the new user has an account, call claimReferral with your own id for that user. The first valid claim for an app and installer id wins. Your backend can post the claim to the claims API instead.
Grant the reward from the webhook
Verify the signature on the referral.claimed webhook, then credit the inviter in your system. The reward, its rules and the payout are yours to set, so the same flow fits credits, upgrades or cash.
Check results in the Referrals report
The Referrals report lists claims newest first and exports up to 10,000 rows as CSV. REST and MCP return the same data, so a question about who invited whom has an answer in one place.
Read the invitation and claim it
import WarpLink
// First screen: offer the invitation paste.
WarpLinkPasteButton { result in
if case .success(let link) = result, link != nil { showInvitationApplied() }
}
// After sign-up: credit the invite with your own id for the new user.
WarpLink.claimReferral(installerId: user.warplinkId) { result in
guard case .success(let claim) = result, claim.status == .claimed else { return }
// Recorded. Your webhook grants the reward.
}// Nothing to paste on Android: the Play install referrer carries the invitation.
// After sign-up: credit the invite with your own id for the new user.
WarpLink.claimReferral(user.warplinkId) { result ->
result.onSuccess { claim ->
if (claim.status == ReferralClaimStatus.CLAIMED) {
// Recorded. Your webhook grants the reward.
}
}
}import { WarpLink } from '@warplink/react-native'
// The person pastes the invitation into a field on your onboarding screen.
const link = await WarpLink.redeemInvitation(pastedText)
if (link) showInvitationApplied()
// After sign-up: credit the invite with your own id for the new user.
const claim = await WarpLink.claimReferral(user.warplinkId)
if (claim.status === 'claimed') {
// Recorded. Your webhook grants the reward.
}import 'package:warplink_flutter/warplink_flutter.dart';
// The person pastes the invitation into a field on your onboarding screen.
final link = await WarpLink.redeemInvitation(pastedText);
if (link != null) showInvitationApplied();
// After sign-up: credit the invite with your own id for the new user.
final claim = await WarpLink.claimReferral(user.warplinkId);
if (claim.status == ReferralClaimStatus.claimed) {
// Recorded. Your webhook grants the reward.
}What you get
- Linking
- Referral links on your app's aplnk.to address or a custom domain, an invitation page for iPhone visitors without the app, and the Play install referrer on Android.
- Attribution
- Each claim records an exact or an estimated match. Exact matches come from the install token, the Android referrer or a link open. Estimates use probabilistic matching on iPhone and carry a confidence value. An exact claim replaces an estimate.
- Analytics
- The Referrals report lists claims newest first, with CSV export up to 10,000 rows. The same data is on REST at GET /v1/referrals and over MCP with list_referrals.
Common questions
How does a referral get credited?
The inviter shares a referral link. When the friend installs and signs up, your app calls claimReferral with your id for that user. We match the install to the link, record the claim and send a signed referral.claimed webhook to your backend.
Who grants the reward?
You do. We match the install and keep the record. Your backend reads the webhook and applies your own reward and rules, whether that is a credit, an upgrade or a payout.
How does the iPhone handoff work?
A visitor without the app sees an invitation page, then the App Store. At first launch, WarpLinkPasteButton lets the person paste the invitation with a tap. The person decides to paste; the SDK does not read the clipboard by itself.
Which SDK version do I need?
Use SDK 1.2.0 or later. It is published for iOS, Android, React Native and Flutter, and it includes claimReferral, redeemInvitation and WarpLinkPasteButton.
What happens when two claims arrive for one friend?
The first valid claim for an app and installer id wins. A later claim is recorded and points at the first, so the inviter is credited once. A claim outside the credit window is flagged for your review.
Can my backend make the claim?
Yes. Post to /v1/referrals/claims with an API key that has the referrals:write scope and an Idempotency-Key header. Use it when sign-up happens on your server.