tracking-retention

name: tracking-retention description: RetentionTracker, UserTargetingManager, D0/D1/D3/D7/D10/D15/D20/D25/D30 milestones, first five opens/sessions, user segmentation, and engagement analytics

Tracking & Retention

Overview

The starter kit includes a comprehensive user tracking and retention system mirrored from the Status Saver template. It automatically tracks app opens, sessions, daily active days, first-five open/session milestones, and retention milestones (D0, D1, D3, D7, D10, D15, D20, D25, D30). It also provides user segmentation for targeted offers.

Prerequisites

• Starter Kit integrated (see starter-kit/SKILL.md)
• Analytics initialized (see skills/analytics/SKILL.md)
• LocalStorage initialized in starter kit core

Architecture

The tracking system lives entirely in the starter kit:

starter_kit/lib/features/analytics/domain/services/
├── analytics_service.dart         # Unified analytics facade
├── retention_tracker.dart         # Core retention tracking (singleton)
└── user_targeting_manager.dart    # User segmentation (singleton)

starter_kit/lib/features/analytics/domain/utils/
└── analytics_names.dart           # Event name constants

Components

RetentionTracker

Singleton that tracks:

• First install date — When the app was first opened
• Last open date — Most recent app open
• Total app opens — Lifetime open count
• Session timestamps — Every session start
• Daily open dates — Unique days the app was opened

Key Methods:

Automatic Events Logged:

Firebase Automatic Event Mirrors

Firebase automatically logs first_open; Mixpanel/PostHog do not. StarterKit.initialize should mirror it once when RetentionTracker.getTotalAppOpens() == 1 after automatic trackAppOpen(...) completes.

Do not create a fake Firebase first_open event with app code. Firebase already owns that automatic event name.

Firebase also infers app_remove when this app is uninstalled. The app cannot emit an uninstall event after it has been removed. For Mixpanel/PostHog, use backend or push-provider uninstall detection if that signal is required.

UserTargetingManager

Segmentation logic using RetentionTracker data:

Engagement Levels:

• FIRST_TIME — First session ever
• LOW — <3 days active or <5 total opens
• MEDIUM — 3-6 days active or 5-15 opens
• HIGH — 7-20 days active or 15-50 opens
• POWER_USER — 20+ days active or 50+ opens

Key Methods:

Implementation

Initialize in main.dart

void main() async {
  // ... Firebase + StarterKit init ...

  await StarterKit.initialize(
    analyticsUserId: installId,
    mixpanelToken: AppEnv.mixpanelToken,
    mixpanelDistinctId: installId,
  );

  runApp(const MyApp());
}

Do not call RetentionTracker.trackAppOpen(...) or UserTargetingManager.startTracking(...) separately for startup tracking unless autoTrackAppOpen: false is set and the host app intentionally owns the lifecycle.

Use for Targeted Features

// Show paywall only to returning non-subscribers
final targeting = UserTargetingManager.instance;
if (targeting.isReturningUser() && !isSubscribed) {
  showPaywall();
}

// Show special offer to loyal users
if (targeting.isLoyalUser()) {
  showLoyaltyReward();
  targeting.logOfferShown('loyalty_reward');
}

// Adjust ad frequency by engagement
final level = targeting.getEngagementLevel();
if (level == UserEngagementLevel.POWER_USER) {
  // Fewer ads for power users
} else if (level == UserEngagementLevel.LOW) {
  // More aggressive monetization
}

Interaction Map

• Analytics → All retention events flow through AnalyticsService to Firebase + Mixpanel/PostHog
• Ads → Use engagement level to adjust ad frequency
• Paywall / IAP → Use user segment to target offers
• Onboarding → isFirstTimeUser() determines whether to show onboarding
• Push Notifications → Segment tags for targeted notifications
• Remote Config → Can combine with remote config for A/B testing

Checklist

• StarterKit.initialize receives analyticsUserId and Mixpanel config when Mixpanel startup events are required
• Analytics service properly initialized
• Retention events appearing in Firebase DebugView and Mixpanel/PostHog live events when configured
• first_open is mirrored only outside Firebase if the exact event name is required
• app_remove is treated as Firebase automatic / backend-only, not client-side app code
• User segments logged on app open
• Targeting logic integrated with paywall/ads decisions