Implementing Referral Gamification (Invite Friends, Get Bonus) in Mobile App
Referral program looks simple—shared link, friend installs, both get bonus. In practice, two-thirds of implementations have attribution or payout bugs. Most common: friend installed but bonus didn't credit. Users get angry, support overloaded. Attribution of install to referral link—technically non-trivial.
Install Attribution
Deferred Deep Link—key mechanism. User taps referral link on iOS, goes to App Store (app not installed), installs, opens—app must "remember" it opened via referral link from specific user.
Native iOS Universal Link and Android App Link don't preserve context through Store. Need deferred deep link SDK:
-
Branch.io—industry standard for referrals. SDK on iOS and Android on first open queries Branch API, which matches install with prior session over link via device fingerprint (IP + device model + OS version + timestamp correlation). Returns
referrer_idandcampaign_data. - Firebase Dynamic Links—free alternative, but Google announced deprecation (2024). Requires migration.
- Adjust / AppsFlyer—MMP (mobile measurement partners), more precise via probabilistic fingerprinting + deterministic (IDFA/GAID with consent).
On client first launch: BranchUniversalObject.getFirstReferringParams() → if contains referrer_id → POST to server /referrals/activate with {referrer_id, new_user_id}.
Server-Side Validation
Server doesn't just credit on /referrals/activate. Checks:
-
new_user_idhasn't already activated referral (one bonus per account). -
referrer_id—real user. - Condition met (if bonus on first purchase, not install—wait
first_purchaseevent). - Anti-fraud: new user IP doesn't match referrer IP (self-referral).
Bonus credited via LedgerService.credit()—atomically, with transaction_type: referral_reward.
UI: Referral Screen
Referral link—https://app.example.com/r/{referral_code}—copied one tap or shared via UIActivityViewController / ShareCompat.IntentBuilder. QR code—CIFilter(name: "CIQRCodeGenerator") on iOS, ZXing or ML Kit Barcode on Android.
Referral progress: how many friends invited, how many activated, how much earned. Friend list with status—invited / installed / activated / rewarded. Motivates more sharing.
Bonus credit animation on app open after successful referral—Lottie, confetti via CAEmitterLayer, with bonus amount centered.
Referral Program Level Gamification
Basic: invite 1 → get bonus X. Gamified: reach levels. Example:
| Level | Invites | Bonus per Friend |
|---|---|---|
| Bronze | 1–4 | 50 coins |
| Silver | 5–14 | 75 coins |
| Gold | 15+ | 100 coins |
Progress bar to next level on referral screen. Notification "2 more friends to Gold"—push via FCM/APNS with deep link.
Two-way bonus (referrer and new user both rewarded) converts better than one-way—show both amounts in share message: "Come, get 100 coins, I'll get 100 too".
Process
Choose and integrate deferred deep link SDK → server referral validation logic → referral screen UI + animations → push notifications on status → QA (test install via referral link on real devices) → publication.
Timeline Estimates
Implementation with Branch.io, referral screen, server validation, basic animations: 2–3 working days with ready API. With gamified levels and referral analytics: 4–5 days.







