lapsed-user

# Lapsed User Re-Engagement Generator

Generate production infrastructure for detecting users who haven't opened the app in X days, showing personalized return screens that highlight what they missed, and optionally presenting win-back incentives to recover churned or lapsing users.

## When This Skill Activates

Use this skill when the user:
- Asks about "lapsed user" detection or re-engagement
- Wants to handle "returning user" or "inactive user" scenarios
- Mentions "re-engagement" screens or flows
- Asks about "win-back" offers for churned users
- Wants to detect when a "user hasn't opened app" in a while
- Asks about "user retention" or "come back" experiences

## Pre-Generation Checks

### 1. Project Context Detection
- [ ] Check Swift version (requires Swift 5.9+)
- [ ] Check deployment target (iOS 17+ / macOS 14+ for @Observable)
- [ ] Identify source file locations and project structure

### 2. Existing Engagement Tracking
Search for existing engagement or analytics infrastructure:
```
Glob: **/*Analytics*.swift, **/*Engagement*.swift, **/*Tracker*.swift, **/*Activity*.swift
Grep: "lastActiveDate" or "UserDefaults" or "scenePhase" or "applicationDidBecomeActive"
```

If existing tracking found:
- Ask if user wants to integrate with it or build standalone
- If integrating, adapt templates to use existing storage/events

### 3. Push Notification Setup
Search for existing push notification configuration:
```
Glob: **/*Notification*.swift, **/*Push*.swift
Grep: "UNUserNotificationCenter" or "UNNotification" or "registerForRemoteNotifications"
```

If push notifications are configured, offer push-based re-engagement as an option.

### 4. Conflict Detection
Search for existing lapsed user handling:
```
Glob: **/*LapsedUser*.swift, **/*WinBack*.swift, **/*ReturnExperience*.swift, **/*Reengag*.swift
Grep: "lapsedUser" or "winBack" or "returnExperience" or "daysInactive"
```

If existing implementation found:
- Ask if user wants to replace or extend it
- If extending, generate only the missing pieces

## Configuration Questions

Ask user via AskUserQuestion:

1. **Inactivity threshold?**
   - 7 days (light engagement apps — social, news)
   - 14 days (moderate engagement — productivity, fitness) — recommended
   - 30 days (low-frequency apps — finance, travel)
   - Custom (user specifies days)

2. **Re-engagement strategy?**
   - What-You-Missed (highlight new content, features, or activity since last visit)
   - Special Offer (discount or extended trial for lapsed subscribers)
   - Fresh Start (reset onboarding highlights, re-introduce key features)
   - All of the above (tiered by lapse duration)

3. **Trigger mechanism?**
   - Show on app return (present sheet when user opens app after inactivity)
   - Via push notification (schedule local notification after X days inactive)
   - Both — recommended

4. **Include analytics events?**
   - Yes (track lapse detection, return screen shown, CTA tapped, offer redeemed) — recommended
   - No (skip analytics, just UI)

## Generation Process

### Step 1: Read Templates
Read `templates.md` for production Swift code.

### Step 2: Create Core Files
Generate these files:
1. `InactivityTracker.swift` — Tracks last active date, calculates days since last use
2. `LapsedUserDetector.swift` — Evaluates inactivity against thresholds, returns lapse category
3. `LapsedUserManager.swift` — Orchestrator combining detection + experience selection + analytics

### Step 3: Create UI Files
4. `ReturnExperienceView.swift` — Personalized "Welcome back" screen with what-you-missed
5. `WinBackOfferView.swift` — Special offer screen for lapsed subscribers

### Step 4: Create Integration File
6. `LapsedUserModifier.swift` — SwiftUI ViewModifier for root view auto-detection and presentation

### Step 5: Determine File Location
Check project structure:
- If `Sources/` exists → `Sources/LapsedUser/`
- If `App/` exists → `App/LapsedUser/`
- Otherwise → `LapsedUser/`

## Output Format

After generation, provide:

### Files Created
```
LapsedUser/
├── InactivityTracker.swift       # Tracks last active date in UserDefaults
├── LapsedUserDetector.swift      # Evaluates inactivity thresholds
├── LapsedUserManager.swift       # Orchestrator for detection + experience
├── ReturnExperienceView.swift    # Welcome back screen with highlights
├── WinBackOfferView.swift        # Special offer for lapsed subscribers
└── LapsedUserModifier.swift      # ViewModifier for auto-detection
```

### Integration at App Launch

**Attach to root view:**
```swift
@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .lapsedUserDetection()
        }
    }
}
```

**Manual detection (if you need control over presentation):**
```swift
struct ContentView: View {
    @State private var manager = LapsedUserManager()

    var body: some View {
        NavigationStack {
            MainView()
        }
        .task {
            await manager.checkOnReturn()
        }
        .sheet(item: $manager.returnExperience) { experience in
            ReturnExperienceView(experience: experience)
        }
        .sheet(item: $manager.winBackOffer) { offer in
            WinBackOfferView(offer: offer)
        }
    }
}
```

**With custom thresholds:**
```swift
let detector = LapsedUserDetector(
    recentThreshold: 7,     // 1-7 days: recently inactive
    moderateThreshold: 21,  // 8-21 days: moderately lapsed
    longTermThreshold: 60   // 22-60 days: long-term lapsed
)
```

**Win-back offer for lapsed subscribers:**
```swift
WinBackOfferView(offer: WinBackOffer(
    headline: "We missed you!",
    discount: .percentage(30),
    originalPrice: "$9.99/mo",
    offerPrice: "$6.99/mo",
    expiresIn: .days(7),
    productID: "com.app.premium.monthly"
))
```

### Testing

```swift
@Test
func detectsRecentlyInactiveUser() async {
    let tracker = InactivityTracker(store: MockUserDefaults())
    tracker.recordActivity()

    // Simulate 5 days of inactivity
    tracker.override(lastActiveDate: Calendar.current.date(byAdding: .day, value: -5, to: Date())!)

    let detector = LapsedUserDetector(tracker: tracker)
    let category = detector.evaluate()
    #expect(category == .recentlyInactive)
}

@Test
func longTermLapsedUserGetsWinBackOffer() async {
    let tracker = InactivityTracker(store: MockUserDefaults())
    tracker.override(lastActiveDate: Calendar.current.date(byAdding: .day, value: -45, to: Date())!)

    let manager = LapsedUserManager(tracker: tracker, isSubscriber: true)
    await manager.checkOnReturn()

    #expect(manager.winBackOffer != nil)
    #expect(manager.returnExperience != nil)
}

@Test
func activeUserSeesNothing() async {
    let tracker = InactivityTracker(store: MockUserDefaults())
    tracker.recordActivity() // Just opened the app

    let manager = LapsedUserManager(tracker: tracker)
    await manager.checkOnReturn()

    #expect(manager.returnExperience == nil)
    #expect(manager.winBackOffer == nil)
}
```

## Common Patterns

### Detect on App Become Active
```swift
// In your App struct or root view
.onChange(of: scenePhase) { _, newPhase in
    if newPhase == .active {
        inactivityTracker.recordActivity()
    }
}
```

### Show Return Screen
```swift
// LapsedUserManager determines what to show based on:
// 1. How long the user has been away
// 2. Whether they are/were a subscriber
// 3. What changed in the app since their last visit
let experience = manager.buildReturnExperience(
    category: .moderatelyLapsed,
    changelog: appChangelog.since(tracker.lastActiveDate)
)
```

### Trigger Win-Back Offer
```swift
// Only show win-back to users who previously had a subscription
if detector.category.isLapsed && subscriptionStatus == .expired {
    manager.presentWinBackOffer(
        discount: .percentage(30),
        duration: .days(7)
    )
}
```

## Gotchas

### Background App Refresh vs Actual Absence
Background app refresh triggers `applicationDidBecomeActive` without user interaction. Use `scenePhase` changes to `.active` paired with the app being in `.background` (not `.inactive`) to avoid false positives. Track whether the user actually interacted (foreground time > threshold).

### Timezone-Aware Date Math
Always use `Calendar.current` for day calculations, not raw `TimeInterval` division. A user who opened the app at 11pm and returns at 1am the next day has been away for 2 hours, not 1 day.

```swift
// Wrong - raw seconds
let daysAway = Date().timeIntervalSince(lastActive) / 86400

// Right - calendar-aware
let daysAway = Calendar.current.dateComponents([.day], from: lastActive, to: Date()).day ?? 0
```

### Don't Annoy Deliberate Break-Takers
Provide a "Don't show again" option on the return screen. Respect user preferences — if they dismiss the return experience, increase the threshold before showing again. Store dismissal count and back off exponentially.

### Avoid Stacking with Other Modals
If your app has onboarding, what's-new, or review prompts, coordinate with them. Don't show a return screen AND a review prompt AND a what's-new modal on the same launch. Use a presentation queue.

### Testing Date-Dependent Logic
Inject the date source so tests can control "now":
```swift
let tracker = InactivityTracker(
    store: mockDefaults,
    currentDate: { Date(timeIntervalSince1970: 1700000000) }
)
```

## References

- **templates.md** — All production Swift templates
- Related: `generators/subscription-lifecycle` — Subscription state management
- Related: `generators/whats-new` — What's New screen generation