nudge

A local-first nudge engine for Flutter. Log behavioural events on device, describe conditions with a fluent DSL, and fire rate prompts, upsells and tips at the right moment — with cooldowns, caps, outcomes and chaining.

📖 Documentation: docs.page/AngeloAvv/nudge

Why

Every app ends up writing the same logic by hand: ask for a review after the third successful order, but not right after an error, and not more than three times a year. nudge turns it into declarations, evaluated on device:

final nudge = await Nudge.initialize();

// Log behaviour
nudge.logEvent('order_completed', {'total': 42.5});

// Declare a nudge and its policies
nudge
    .define('rating_prompt')
    .when(
      nudge.when().event('order_completed').count().greaterThanOrEqual(3)
          .and(nudge.when().event('error').session().current().exists().not()),
    )
    .group('interruptive')
    .groupOncePerSession()
    .cooldown(const Duration(days: 14))
    .maxFires(3, per: const Duration(days: 365))
    .register();

// At a natural pause, ask the engine
final fire = nudge.checkpoint(group: 'interruptive');
if (fire != null) {
  await InAppReview.instance.requestReview();
  fire.complete(NudgeOutcome.unknown);
}

Features

• Local-first: events stay on device (ObjectBox); evaluation is synchronous
• Fluent conditions: counts, attribute filters and aggregates, distinct sessions, active days, streaks, recency and inactivity, install age, loose funnels with windows and drop-off
• Nudges with memory: cooldowns, caps, once per session, group caps and priorities, outcome-based policies — persisted across launches
• Chaining: nudges can depend on other nudges' fires and outcomes
• Explainable: explainNudge(id) shows which part of a condition or policy is blocking
• Testable: in-memory storage and an injectable clock
• Widgets: NudgeBuilder, NudgeListener, NudgeFireListener

Installation

dependencies:
  nudge: ^0.1.0

Supported platforms: Android, iOS, macOS, Linux, Windows.

Learn more

• Getting started
• Core concepts
• Recipes: rating prompt, paywall, onboarding, abandoned cart, feature discovery, streaks, win-back, push permission, NPS and referral, activation, guest to account, frequency capping

License

nudge is available under the GNU General Public License Version 3. See the LICENSE file for more info.