rshankras/referral-system

Referral System Generator

Generate a production referral/invite system with unique code generation, deep link sharing, reward tracking, fraud prevention, and SwiftUI views for inviting friends and monitoring referral performance.

When This Skill Activates

Use this skill when the user:

• Asks to "add a referral system" or "referral codes"
• Wants to "invite friends" or "refer a friend" flow
• Mentions "viral growth" or "invitation system"
• Asks about "referral rewards" or "referral tracking"
• Wants "invite codes" or "shareable invite links"

Pre-Generation Checks

1. Project Context Detection

• [ ] Check Swift version (requires Swift 5.9+)
• [ ] Check deployment target (iOS 17+ / macOS 14+ for @Observable and SwiftData)
• [ ] Identify source file locations
• [ ] Check for existing entitlements (Associated Domains for deep links)

2. Conflict Detection

Search for existing referral/invite code:

Glob: **/*Referral*.swift, **/*Invite*.swift, **/*InviteCode*.swift
Grep: "referralCode" or "inviteCode" or "ReferralManager"

If existing referral system found:

• Ask if user wants to replace or extend it
• If extending, identify integration points

3. Deep Link Setup Detection

Search for existing deep link handling:

Glob: **/*DeepLink*.swift, **/*UniversalLink*.swift
Grep: "onOpenURL" or "userActivity" or "NSUserActivity"

If deep link handling exists, integrate with it rather than generating a standalone handler.

Configuration Questions

Ask user via AskUserQuestion:

1. Reward type?

   • Both-get (referrer and invitee both earn a reward) -- recommended
   • Referrer-only (only the person who shares gets rewarded)
   • Points-based (both parties earn points toward rewards)

2. Code format?

   • Short alphanumeric (e.g., A7K2M9) -- recommended
   • Custom prefix (e.g., MYAPP-A7K2M9)
   • Username-based (e.g., john-A7K2)

3. Sharing method?

   • Deep link (universal link with embedded code) -- recommended
   • Clipboard copy (copy code to pasteboard)
   • Share sheet (system share with link and message)
   • All of the above

4. Storage?

   • SwiftData (local persistence, recommended for most apps)
   • UserDefaults (lightweight, for simple single-code scenarios)
   • CloudKit (sync across devices)

Generation Process

Step 1: Read Templates

Read templates.md for production Swift code.

Step 2: Create Core Files

Generate these files:

1. ReferralCode.swift -- Model with unique code generation, expiration, usage tracking
2. ReferralManager.swift -- @Observable manager for code lifecycle and redemption
3. ReferralReward.swift -- Reward configuration, conditions, and fulfillment tracking

Step 3: Create UI Files

4. InviteView.swift -- SwiftUI invite screen with code display and sharing
5. ReferralDashboardView.swift -- Stats view for referral performance

Step 4: Create Integration Files

6. ReferralDeepLinkHandler.swift -- Deep link parsing and redemption triggering

Step 5: Determine File Location

Check project structure:

• If Sources/ exists -> Sources/Referral/
• If App/ exists -> App/Referral/
• Otherwise -> Referral/

Output Format

After generation, provide:

Files Created

Referral/
├── ReferralCode.swift            # Code model with generation and validation
├── ReferralManager.swift         # @Observable manager for code lifecycle
├── ReferralReward.swift          # Reward config and fulfillment tracking
├── InviteView.swift              # Invite screen with share actions
├── ReferralDashboardView.swift   # Referral stats dashboard
└── ReferralDeepLinkHandler.swift # Deep link parsing and redemption

Integration Steps

Add deep link handling in your App struct:

@main
struct MyApp: App {
    @State private var referralManager = ReferralManager()
    private let deepLinkHandler = ReferralDeepLinkHandler()

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(referralManager)
                .onOpenURL { url in
                    if let code = deepLinkHandler.extractCode(from: url) {
                        Task {
                            await referralManager.redeemCode(code)
                        }
                    }
                }
        }
    }
}

Present the invite screen:

struct ProfileView: View {
    @State private var showInvite = false

    var body: some View {
        Button("Invite Friends") { showInvite = true }
            .sheet(isPresented: $showInvite) {
                InviteView()
            }
    }
}

Show referral dashboard:

NavigationLink("My Referrals") {
    ReferralDashboardView()
}

Testing

@Test
func generatedCodeIsUnique() async throws {
    let manager = ReferralManager(store: InMemoryReferralStore())

    let code1 = await manager.generateCode(for: "user-1")
    let code2 = await manager.generateCode(for: "user-2")

    #expect(code1.value != code2.value)
}

@Test
func redemptionGrantsReward() async throws {
    let manager = ReferralManager(store: InMemoryReferralStore())
    let code = await manager.generateCode(for: "referrer-1")

    let result = await manager.redeemCode(code.value, redeemedBy: "invitee-1")

    #expect(result == .success)
    #expect(manager.rewards(for: "referrer-1").count == 1)
    #expect(manager.rewards(for: "invitee-1").count == 1)
}

@Test
func selfReferralIsRejected() async throws {
    let manager = ReferralManager(store: InMemoryReferralStore())
    let code = await manager.generateCode(for: "user-1")

    let result = await manager.redeemCode(code.value, redeemedBy: "user-1")

    #expect(result == .fraudDetected(.selfReferral))
}

@Test
func expiredCodeIsRejected() async throws {
    let manager = ReferralManager(store: InMemoryReferralStore())
    let code = ReferralCode(
        value: "EXPIRED1",
        ownerID: "user-1",
        expiresAt: Date.distantPast
    )

    let result = await manager.redeemCode(code.value, redeemedBy: "user-2")

    #expect(result == .expired)
}

Common Patterns

Generate and Share a Referral Code

// Generate code for current user
let code = await referralManager.generateCode(for: currentUserID)

// Share via system share sheet
let shareURL = deepLinkHandler.buildShareURL(for: code)
let message = "Join me on MyApp! Use my code \(code.value) for a bonus."
let activityItems: [Any] = [message, shareURL]

Redeem a Referral Code

// On app launch or deep link open
let result = await referralManager.redeemCode(codeString, redeemedBy: currentUserID)

switch result {
case .success:
    showRewardAnimation()
case .alreadyRedeemed:
    showAlert("You've already used a referral code.")
case .expired:
    showAlert("This referral code has expired.")
case .fraudDetected(let reason):
    logger.warning("Fraud detected: \(reason)")
case .invalid:
    showAlert("Invalid referral code.")
}

Track Rewards

// Check pending rewards
let pending = referralManager.pendingRewards(for: currentUserID)
for reward in pending {
    await fulfillReward(reward)
    await referralManager.markFulfilled(reward)
}

Gotchas

Fraud Prevention

• Self-referral: Always verify referrer ID != redeemer ID. Users will try creating alt accounts.
• Device fingerprinting: Consider storing device identifiers to detect multi-account abuse.
• Rate limiting: Cap the number of referrals per user per time period (e.g., 50 per month).
• Code reuse: Each invitee should only be able to redeem one referral code ever.

App Store Guidelines

• Guideline 3.1.1: Do not offer real-money rewards or gift cards for referrals without proper IAP integration.
• Guideline 3.2.2(vii): Referral systems must not manipulate App Store ratings or reviews.
• Incentivized installs: Apple may reject apps that reward users purely for downloading. Tie rewards to meaningful in-app actions (e.g., completing a first task, making a purchase).

Deep Link Expiration

• Universal links require an apple-app-site-association file on your server.
• Referral deep links should have a TTL (default 30 days) to prevent stale code accumulation.
• Handle the case where a user taps a referral link but the app is not installed (redirect to App Store, then capture code on first launch).

Data Privacy

• Referral codes should not expose user PII (no emails or phone numbers in codes).
• Provide opt-out: let users disable their referral code at any time.
• Comply with GDPR/CCPA if tracking referral relationships across users.

References

• templates.md -- All production Swift templates
• Related: generators/deep-linking -- Universal link and deep link infrastructure
• Related: generators/share-card -- Visual share cards for social sharing
• Related: generators/analytics-setup -- Track referral funnel events