Happy Review

Event-driven in-app review prompts for Flutter. Trigger reviews at moments of user satisfaction — not arbitrary launch counts.

Read the full strategy behind this library: The Art of Asking: In-App Review Strategy for Mobile Applications

The Problem

Most apps request reviews based on how many times the app was opened. This is a bad practice:

• Opening the app doesn't mean enjoying it.
• You interrupt without context — the user hasn't accomplished anything yet.
• You actively generate negative reviews from annoyed users.
• You waste limited OS-level review invocations (Apple caps at 3/year).

The Solution

Happy Review replaces the launch counter with an event-driven approach:

1. Triggers fire when the user completes a happy-path action (purchase, workout, delivery).
2. Prerequisites ensure baseline engagement before any trigger can activate (AND logic).
3. Platform Policy enforces per-platform frequency rules aligned with Apple/Google restrictions.
4. Conditions add business-level guards (days since install, cooldowns, custom logic).
5. Emotional Filter shows a pre-dialog ("Are you enjoying the app?") that routes satisfied users to the OS review and captures feedback from unsatisfied users — privately.

logEvent() -> Trigger met? -> Prerequisites OK? -> Platform policy OK? -> Conditions pass?
                                                                              |
                                                                       Pre-dialog shown
                                                                      /       |        \
                                                                Positive   Later    Negative
                                                                   |         |          |
                                                            OS Review    Skip      Feedback form

Installation

dependencies:
  happy_review: ^0.2.1

Platform Support

Quick Start

import 'package:happy_review/happy_review.dart';

// 1. Configure once at app startup.
await HappyReview.instance.configure(
  storageAdapter: MyStorageAdapter(), // You provide the implementation.
  triggers: [
    const HappyTrigger(eventName: 'purchase_completed', minOccurrences: 3),
  ],
  dialogAdapter: DefaultReviewDialogAdapter(),
);

// 2. Log events after happy-path actions.
await HappyReview.instance.logEvent(context, 'purchase_completed');

That's it. After 3 purchases, the pre-dialog appears. If the user responds positively, the OS review is requested. If negatively, a feedback form is shown.

Configuration

Triggers

Define which events can activate the review flow (OR logic — any single trigger is enough):

triggers: [
  const HappyTrigger(eventName: 'purchase_completed', minOccurrences: 3),
  const HappyTrigger(eventName: 'streak_reached', minOccurrences: 1),
]

Prerequisites

Events that must ALL have occurred before any trigger can fire (AND logic):

prerequisites: [
  // User must finish onboarding before any review flow can start.
  const HappyTrigger(eventName: 'onboarding_finished', minOccurrences: 1),
  // User must have used the app at least 5 times.
  const HappyTrigger(eventName: 'app_session', minOccurrences: 5),
]

This is useful for ensuring baseline engagement. Triggers are OR ("any of these can activate"), prerequisites are AND ("all of these must be true first").

Conditions

Add business rules that must all pass before the flow starts:

conditions: [
  // Wait at least 7 days after first launch.
  const MinDaysAfterInstall(days: 7),

  // Don't show more than 3 times total.
  const MaxPromptsShown(maxPrompts: 3),

  // Custom logic — anything you need.
  CustomCondition(
    name: 'no_recent_support_ticket',
    evaluate: () async => !(await supportRepo.hasRecentTicket()),
  ),
]

Built-in conditions:

Platform Policy

Per-platform frequency rules that act as a safety layer aligned with OS restrictions:

platformPolicy: const PlatformPolicy(
  ios: PlatformRules(
    cooldown: Duration(days: 120),
    maxPrompts: 3,
    maxPromptsPeriod: Duration(days: 365),
  ),
  android: PlatformRules(
    cooldown: Duration(days: 60),
    maxPrompts: 3,
    maxPromptsPeriod: Duration(days: 365),
  ),
  macOS: PlatformRules(
    cooldown: Duration(days: 120),
    maxPrompts: 3,
    maxPromptsPeriod: Duration(days: 365),
  ),
)

Sensible defaults are applied if you don't specify a policy.

Callbacks

React to every step of the review flow:

onPreDialogShown: () => analytics.log('pre_dialog_shown'),
onPreDialogPositive: () => analytics.log('user_happy'),
onPreDialogNegative: () => analytics.log('user_unhappy'),
onPreDialogRemindLater: () => analytics.log('user_remind_later'),
onPreDialogDismissed: () => analytics.log('dialog_dismissed'),
onReviewRequested: () => analytics.log('os_review_requested'),
onFeedbackSubmitted: (feedback) => sendToBackend(feedback),

Adapters

Happy Review uses adapters so you control how things look and where state is stored.

Dialog Adapter

Controls the pre-dialog and feedback UI.

Option 1: Default adapter with config

dialogAdapter: DefaultReviewDialogAdapter(
  preDialogConfig: const DefaultPreDialogConfig(
    title: 'Enjoying our app?',
    positiveLabel: 'Love it!',
    negativeLabel: 'Not really',
    remindLaterLabel: 'Maybe later', // Set to null to hide this button.
  ),
  feedbackConfig: const DefaultFeedbackDialogConfig(
    title: 'What could we improve?',
    categories: ['Performance', 'Design', 'Features'],
    showContactOption: true,
  ),
)

Option 2: Fully custom UI

Implement ReviewDialogAdapter to use your own widgets:

class MyReviewDialogAdapter extends ReviewDialogAdapter {
  @override
  Future<PreDialogResult> showPreDialog(BuildContext context) async {
    final result = await showModalBottomSheet<bool>(
      context: context,
      builder: (_) => MySatisfactionSheet(),
    );
    if (result == null) return PreDialogResult.dismissed;
    return result ? PreDialogResult.positive : PreDialogResult.negative;
  }

  @override
  Future<FeedbackResult?> showFeedbackDialog(BuildContext context) async {
    return Navigator.of(context).push<FeedbackResult>(
      MaterialPageRoute(builder: (_) => MyFeedbackScreen()),
    );
  }
}

Option 3: No adapter (direct review)

Omit dialogAdapter to skip the pre-dialog and request the OS review directly when triggers fire.

Storage Adapter

Controls where event counts and internal state are persisted. This is a required parameter — the library has zero opinion on your storage layer.

Implement ReviewStorageAdapter with your preferred backend:

class HiveStorageAdapter extends ReviewStorageAdapter {
  final Box _box;

  HiveStorageAdapter(this._box);

  @override
  Future<int> getInt(String key, {int defaultValue = 0}) async =>
      _box.get(key, defaultValue: defaultValue);

  @override
  Future<void> setInt(String key, int value) => _box.put(key, value);

// ... implement remaining methods
}

The example app includes a SharedPreferencesStorageAdapter you can use as reference or copy directly into your project.

Return Values

logEvent returns a ReviewFlowResult so you know exactly what happened:

Kill Switch

Disable the library at runtime without redeploying (e.g., via remote config):

// At configure time:
await HappyReview.instance.configure(
  storageAdapter: myStorageAdapter,
  enabled: false, // All logEvent calls return ReviewFlowResult.disabled.
  // ...
);

// Or toggle at runtime:
HappyReview.instance.setEnabled(remoteConfig.getBool('enable_review_prompt'));

Query State

Inspect internal state without triggering the review flow:

// How many times has this event been logged?
final count = await HappyReview.instance.getEventCount('purchase_completed');

// How many times has the review prompt been shown?
final prompts = await HappyReview.instance.getPromptsShownCount();

// When was the last prompt shown?
final lastDate = await HappyReview.instance.getLastPromptDate();

Debug Mode

Enable debug mode during development to observe the full pipeline via logs:

await HappyReview.instance.configure(
  storageAdapter: myStorageAdapter,
  debugMode: true, // Enables detailed logging.
  // ...
);

In debug mode:

• Detailed logs are printed via debugPrint at every pipeline stage.
• All checks (prerequisites, platform policy, conditions) are still enforced.

To test the dialog flow during development, use a relaxed platform policy instead:

platformPolicy: const PlatformPolicy(
  android: PlatformRules(
    cooldown: Duration(seconds: 10),
    maxPrompts: 99,
    maxPromptsPeriod: Duration(days: 365),
  ),
  ios: PlatformRules(
    cooldown: Duration(seconds: 10),
    maxPrompts: 99,
    maxPromptsPeriod: Duration(days: 365),
  ),
  macOS: PlatformRules(
    cooldown: Duration(seconds: 10),
    maxPrompts: 99,
    maxPromptsPeriod: Duration(days: 365),
  ),
),

Debug Panel

Embed a HappyReviewDebugPanel widget in any screen to visualize the full pipeline state at a glance:

const HappyReviewDebugPanel()

The panel shows: enabled status, triggers (with counts), prerequisites, platform policy, conditions, prompts shown, and last prompt date. It includes a refresh button and only renders in debug builds.

You can also access the raw data programmatically:

final snapshot = await HappyReview.instance.getDebugSnapshot();
print(snapshot.triggers.first.currentCount); // e.g., 2
print(snapshot.platformPolicyAllows); // true/false

Testing

Import happy_review/testing.dart to get fakes for your tests — no mocking library needed:

import 'package:happy_review/happy_review.dart';
import 'package:happy_review/testing.dart';

// In-memory storage that works like a real backend.
final storage = FakeStorageAdapter();

// Dialog adapter that returns predetermined results.
// Defaults to PreDialogResult.positive.
final adapter = FakeDialogAdapter();

// Simulate an unhappy user with feedback:
final unhappyAdapter = FakeDialogAdapter(
  preDialogResult: PreDialogResult.negative,
  feedbackResult: FeedbackResult(comment: 'Too slow'),
);

await HappyReview.instance.configure(
  storageAdapter: storage,
  triggers: [const HappyTrigger(eventName: 'purchase', minOccurrences: 1)],
  dialogAdapter: adapter,
);

Use Cases

await HappyReview.instance.configure(
  storageAdapter: myStorage,
  triggers: [
    const HappyTrigger(eventName: 'purchase_completed', minOccurrences: 3),
  ],
  prerequisites: [
    const HappyTrigger(eventName: 'onboarding_finished', minOccurrences: 1),
  ],
  dialogAdapter: DefaultReviewDialogAdapter(),
);

// After a successful purchase:
await HappyReview.instance.logEvent(context, 'purchase_completed');

await HappyReview.instance.configure(
  storageAdapter: myStorage,
  triggers: [
    const HappyTrigger(eventName: 'workout_completed', minOccurrences: 10),
    const HappyTrigger(eventName: 'streak_7_days', minOccurrences: 1),
  ],
  conditions: [
    const MinDaysAfterInstall(days: 14),
    const CooldownPeriod(days: 90),
  ],
  dialogAdapter: DefaultReviewDialogAdapter(
    preDialogConfig: const DefaultPreDialogConfig(
      title: 'Crushing your goals!',
      positiveLabel: 'Rate us!',
      negativeLabel: 'Could be better',
    ),
  ),
);

await HappyReview.instance.configure(
  storageAdapter: myStorage,
  triggers: [
    const HappyTrigger(eventName: 'delivery_confirmed', minOccurrences: 2),
  ],
  conditions: [
    const MinDaysAfterInstall(days: 7),
    const MaxPromptsShown(maxPrompts: 3),
    CustomCondition(
      name: 'no_recent_complaint',
      evaluate: () async => !(await supportRepo.hasOpenTicket()),
    ),
  ],
  dialogAdapter: DefaultReviewDialogAdapter(),
);

await HappyReview.instance.configure(
  storageAdapter: myStorage,
  triggers: [
    const HappyTrigger(eventName: 'report_exported', minOccurrences: 5),
    const HappyTrigger(eventName: 'project_completed', minOccurrences: 1),
  ],
  prerequisites: [
    const HappyTrigger(eventName: 'profile_setup', minOccurrences: 1),
  ],
  dialogAdapter: DefaultReviewDialogAdapter(
    preDialogConfig: const DefaultPreDialogConfig(
      title: 'How is your experience?',
      positiveLabel: 'Great!',
      negativeLabel: 'Not great',
      remindLaterLabel: 'Ask me later',
    ),
  ),
);

await HappyReview.instance.configure(
  storageAdapter: myStorage,
  triggers: [
    const HappyTrigger(eventName: 'level_completed', minOccurrences: 10),
    const HappyTrigger(eventName: 'boss_defeated', minOccurrences: 1),
  ],
  conditions: [
    const MinDaysAfterInstall(days: 3),
    const CooldownPeriod(days: 60),
  ],
  dialogAdapter: DefaultReviewDialogAdapter(),
);

await HappyReview.instance.configure(
  storageAdapter: myStorage,
  triggers: [
    const HappyTrigger(eventName: 'module_completed', minOccurrences: 3),
    const HappyTrigger(eventName: 'certificate_earned', minOccurrences: 1),
  ],
  dialogAdapter: DefaultReviewDialogAdapter(
    preDialogConfig: const DefaultPreDialogConfig(
      title: 'Congrats on your progress!',
      positiveLabel: 'Love learning here!',
      negativeLabel: 'Needs improvement',
    ),
  ),
);

await HappyReview.instance.configure(
  storageAdapter: myStorage,
  triggers: [
    const HappyTrigger(eventName: 'nps_score_9_or_10', minOccurrences: 1),
  ],
  // No dialogAdapter → OS review is requested directly.
);

await HappyReview.instance.configure(
  storageAdapter: myStorage,
  triggers: [
    const HappyTrigger(eventName: 'app_opened', minOccurrences: 5),
  ],
  // No dialogAdapter, no conditions — just launch count + OS review.
);

// Call on every app start:
await HappyReview.instance.logEvent(context, 'app_opened');

final remoteConfig = FirebaseRemoteConfig.instance;
await remoteConfig.fetchAndActivate();

await HappyReview.instance.configure(
  storageAdapter: myStorage,
  enabled: remoteConfig.getBool('enable_review_prompt'),
  triggers: [
    const HappyTrigger(eventName: 'purchase_completed', minOccurrences: 3),
  ],
  dialogAdapter: DefaultReviewDialogAdapter(),
);

// Or toggle at runtime:
HappyReview.instance.setEnabled(remoteConfig.getBool('enable_review_prompt'));

Full Example

See the example app for a complete working demo that simulates an e-commerce happy flow with prerequisites, debug panel, and kill switch.

Context-First Development

This project follows the Context-First Development (CFD) methodology for AI-assisted development. The repository is structured so that AI agents can operate with persistent, accurate, and efficient context — reducing token waste and eliminating repeated explanations across sessions.

Key elements:

• CLAUDE.md — Root context index referencing specialized documents
• doc/ — Architecture, stack, conventions, and current project status
• doc/decisions/ — Architecture Decision Records (ADRs) for every significant choice
• .claude/commands/ — Slash commands for automated context maintenance

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

MIT