JSONB round-trip test · In-App Referral Program
Status · ExploringUsers share a referral code; when a friend signs up, both receive credit. Design must clarify empty states, fraud detection, and cross-platform behavior.
01
Context & Problem
Problem
No clear user experience for referral tracking, fraud prevention, or cross-platform consistency.
Why now
Feature is in early exploration; fundamental UX questions remain unresolved.
Hypothesis
A transparent referral dashboard with clear empty states and fraud safeguards will drive adoption and trust.
02
Goals & Success
Goals
Maximize referral code sharing and conversionPrevent fraud and self-referralsDeliver consistent experience across web and app
Non-goals
Unlimited referral rewards per userAnonymous referral tracking
Referral Share Rate → TBDCode Redemption Rate → TBDFraud Detection Rate → TBD
03
Scope
In · this release
Referral code generation and displayReferral tracking dashboardFraud detection rulesWeb and app parity
Out · later
Multi-tier referral chainsReferral expiration logicRegional compliance variations
04
Users & Jobs
Primary persona
Existing user seeking rewards
Job to be done
When I want to invite friends, I want to share a code and track their signups, so I can earn rewards.
05
User Stories
P0As a user
As a referrer, I can see an empty state with a clear CTA to share my code when no one has signed up yet.
P0As a user
As a referrer, I can view a list of pending and completed referrals with their status.
P1As a user
As a referrer, I receive a notification when a friend uses my code and signs up.
P0As a user
As the system, I can detect and reject self-referrals or fraudulent signups.
P1As a user
As a user on web, I see the same referral dashboard and sharing options as on the app.
06
User Journey
YOU ARE HERE01 · ENTRY
Discover Referral Program
GoalUser learns referral exists and what reward awaits
FeelsEager to participate
FrictionFeature may be buried or unclear
→
02 · SHARE
Generate and Share Code
GoalUser copies/shares code with zero friction
FeelsConfident code will work
FrictionCross-platform code format inconsistency
→
03 · WAIT
Referral Empty State
GoalUser sees clear visual feedback that code is active and waiting
FeelsReassured nothing is broken
FrictionBlank dashboard confuses user
→
04 · TRACK
Monitor Pending Referrals
GoalUser watches friends progress toward reward unlock
FeelsMotivated to share more
FrictionFraud flag or self-referral rejection unclear
→
05 · REDEEM
Claim Reward
GoalUser applies earned credit to account
FeelsSatisfied and rewarded
FrictionReward may not appear instantly
07
Flows & Information Architecture
- Referral Program
- Referral Dashboard
- Empty StateZero referrals, invite CTA visible
- Active Referrals ListPending / Completed / Disputed
- Rewards SummaryTotal earned, claimable balance
- Share Code Flow
- Code Display ModalCopy / Share buttons, QR optional
- Share Target SelectionWeb: copy link. App: native share.
- Fraud Detection
- Self-Referral BlockSystem rejects same IP/email
- Disputed Referral ViewUser sees why referral flagged
- Referral Dashboard
08
States & Edge Cases
| Screen / Flow | Default | Loading | Empty | Error | Success | Fraud Flag | Offline |
|---|---|---|---|---|---|---|---|
| Referral Dashboard | |||||||
| Empty State (No Referrals) | |||||||
| Active Referrals List | |||||||
| Share Code Modal | |||||||
| Fraud Dispute Detail |
Designed To do Needs attention N/A
09
Rationale & Alternatives
How do we signal to a referrer that their code is active and waiting for first use?
Empty state card with share CTASkeleton list placeholderNo explicit placeholder
Why Explicit empty state reassures user the feature is working and unblocks the next action.
How do we handle suspected self-referrals or fraud?
Silent rejection, no user messageReferral marked 'Disputed' with explanation in user dashboardImmediate account suspension
Why Transparency builds trust; users deserve to know why a referral was rejected.
How do we ensure cross-platform parity between web and app?
Identical UI, same code formatPlatform-native share flows with consistent dashboardWeb-only feature
Why Users expect seamless experience; identical UI prevents confusion.
10
Handoff & Definition of Done
- Empty state screen designed and annotated with copy, share CTA, and spacing
- Fraud detection rules and self-referral block logic documented with examples
- Cross-platform QA matrix (web/iOS/Android) signed off with parity checklist
- Referral status labels ('Pending', 'Completed', 'Disputed') designed with icons and colors
- Error and offline states for dashboard and share flow fully specified
✓
Addressed · Skrut
Empty States
What exactly does the referrer see on first visit with zero referrals — a full-screen empty state card, or just a disabled list with placeholder text?
Error States
When a referral is flagged as fraudulent, does the user see an in-line 'Disputed' label with a tap-to-expand reason, or a separate dispute detail screen?
Error States
If a referral fails to process at sign-up (e.g., duplicate account detected), what error message does the new user see, and is the referrer notified?
Loading & Async
When the referral list is fetching, do we show a skeleton loader, a spinner, or a 'Loading' message, and for how long is it acceptable?
Cross-Platform
On web, does the share code modal open in a popup or inline, and how does this differ from the native app share sheet?
Cross-Platform
If a user generates a code on iOS app and tries to use it on Android web, is there any platform-specific friction in the sign-up flow?
Data & Privacy
What user data (IP, email, device ID) is compared to detect self-referrals, and is this disclosed in privacy terms?
User Types
Does a user who signs up via a referral code see a 'referrer credited' confirmation, and if so, when and where?
Living doc · keep Journey, Flows, States & Rationale current — they go stale fastest.
Built with Skrut — the design-doc auditor.
Built with Skrut — the design-doc auditor.