Flutter Upgrader Package: how to prompt users to upgrade your app

The upgrader package for Flutter detects when a newer version of your app is available in the App Store or Google Play and shows a native-style dialog prompting the user to update. One widget, zero backend — the upgrader checks the store automatically.

What the upgrader package does

Modern app stores offer automatic updates, but there are situations where you need users on a specific version quickly: a critical bug fix, a breaking API change, or a mandatory compliance update. The upgrader package solves this by comparing the installed app version against the version listed in the store and showing a prompt when the store version is higher.

The prompt can be dismissible ("Later"), ignorable for a specific version ("Ignore"), or forced — removing the dismiss option entirely so the user must update before continuing.

Current version: 13.7.0 · Author: larryaasen.com · License: MIT

Install the upgrader package

Add the dependency with the Flutter CLI:

flutter pub add upgrader

Or add it manually to pubspec.yaml:

dependencies:
  upgrader: ^13.7.0

Then run flutter pub get.

UpgradeAlert — dialog prompt

UpgradeAlert wraps any widget and shows a dialog when the upgrader detects a newer version. Place it below MaterialApp in the tree, wrapping your home screen widget:

import 'package:upgrader/upgrader.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My App',
      home: UpgradeAlert(
        child: Scaffold(
          appBar: AppBar(title: const Text('Home')),
          body: const Center(child: Text('Welcome')),
        ),
      ),
    );
  }
}

The dialog shows three buttons by default:

• UPDATE NOW — opens the App Store / Play Store listing
• LATER — dismisses the dialog; it will reappear after durationUntilAlertAgain (default: 3 days)
• IGNORE — suppresses the dialog for that specific version permanently

Cupertino style on iOS

Pass dialogStyle: UpgradeDialogStyle.cupertino to render a native-looking iOS alert instead of the default Material dialog:

UpgradeAlert(
  dialogStyle: UpgradeDialogStyle.cupertino,
  child: myHomeWidget,
)

Force upgrade — remove the dismiss option

Set showLater: false and showIgnore: false together with barrierDismissible: false to block the user until they update:

UpgradeAlert(
  showLater: false,
  showIgnore: false,
  barrierDismissible: false,
  child: myHomeWidget,
)

UpgradeCard — inline card

UpgradeCard renders a Material design card inside your layout instead of a dialog. When no update is detected the widget collapses to zero size, so it is safe to embed anywhere:

Container(
  margin: const EdgeInsets.symmetric(horizontal: 12),
  child: const UpgradeCard(),
)

The card accepts the same showIgnore, showLater, showReleaseNotes, onIgnore, onLater, and onUpdate parameters as UpgradeAlert.

Platform support and Appcast

For Android and iOS the upgrader reads the current version directly from the public Play Store and App Store pages. For all other platforms — and for apps distributed outside the main stores — you host an Appcast XML feed that describes available versions.

Minimal Appcast XML

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0"
     xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle">
  <channel>
    <title>My App</title>
    <item>
      <title>Version 2.1.0</title>
      <sparkle:shortVersionString>2.1.0</sparkle:shortVersionString>
      <sparkle:minimumSystemVersion>12.0</sparkle:minimumSystemVersion>
      <enclosure url="https://example.com/myapp-2.1.0.zip"
                 sparkle:version="2.1.0" />
      <description>Bug fixes and improvements.</description>
    </item>
  </channel>
</rss>

Point the upgrader to your feed via UpgraderAppcastStore:

UpgradeAlert(
  upgrader: Upgrader(
    storeController: UpgraderStoreController(
      onAndroid: () => UpgraderAppcastStore(
        appcastURL: 'https://example.com/appcast.xml',
      ),
    ),
  ),
  child: myHomeWidget,
)

Customization options

Pass an Upgrader instance to UpgradeAlert to control timing, minimum version, and callbacks:

Force update below a minimum version

UpgradeAlert(
  upgrader: Upgrader(minAppVersion: '3.0.0'),
  showLater: false,
  showIgnore: false,
  child: myHomeWidget,
)

React to user choices

UpgradeAlert(
  onIgnore: () => print('user ignored'),
  onLater:  () => print('user chose later'),
  onUpdate: () => print('user tapped update'),
  child: myHomeWidget,
)

Localization

The upgrader package ships with translations for most major languages. Pass a custom UpgraderMessages to override any string:

class MyMessages extends UpgraderMessages {
  @override
  String get buttonTitleUpdate => 'Update the app';

  @override
  String get prompt => 'A newer version is ready.';
}

UpgradeAlert(
  upgrader: Upgrader(messages: MyMessages()),
  child: myHomeWidget,
)

Debug and testing

During development the installed version usually matches the store version, so the dialog never appears. Use the debug flags to force it:

// Show the dialog every launch (development only)
UpgradeAlert(
  upgrader: Upgrader(
    debugDisplayAlways: true,
    debugLogging: true,
  ),
  child: myHomeWidget,
)

For unit tests, pass a mock HTTP client via client and control the OS with upgraderOS to simulate specific store responses without network calls.

FAQ