Upgrader — In-App Update Prompts
for Flutter Apps

What the Upgrader Package Does

upgrader is a Flutter package that watches your app's version against the version published on the App Store or Google Play. When a newer release is found, it surfaces an update dialog — either a full-screen alert or an inline card — without any server-side code on your end.

The package handles the store lookup, version comparison, localisation, and dismissal logic. You control how often the prompt reappears, whether it can be dismissed, and what the dialog text says. The minimal integration is a single widget wrap around your home screen.

How to Install the Upgrader Package

Add upgrader to your Flutter project with the standard pub command:

flutter pub add upgrader

This adds upgrader to your pubspec.yaml and fetches the package. No native configuration is needed for iOS or Android — the package reads the app's bundle identifier and queries the relevant store automatically.

Android — minimum SDK

upgrader uses the Google Play In-App Update API for deep-link behaviour. Set minSdkVersion to at least 21 in your android/app/build.gradle:

// android/app/build.gradle
android {
  defaultConfig {
    minSdkVersion 21
  }
}

iOS — no extra steps

No Info.plist changes are required. upgrader looks up your app on the App Store by bundle ID (CFBundleIdentifier) which is already set in your project.

Using the Upgrader Widget in Your App

The most common way to use upgrader is to wrap your home widget with UpgradeAlert. It intercepts navigation once the store check completes, showing the dialog only when an update is available.

Minimal setup — UpgradeAlert

import 'package:upgrader/upgrader.dart';

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: UpgradeAlert(
        child: MyHomePage(),
      ),
    );
  }
}

That is the complete minimal integration. upgrader handles the rest: store lookup, version comparison, dialog display, and repeat-interval logic.

Inline card — UpgradeCard

If you prefer a banner inside your own UI instead of a blocking dialog, use UpgradeCard. It renders as a Flutter widget you can place anywhere:

Scaffold(
  body: Column(
    children: [
      UpgradeCard(),          // shows only when update is available
      Expanded(child: MyContent()),
    ],
  ),
)

How Upgrader Determines the Latest Version

On iOS and macOS, upgrader calls the iTunes Lookup API with your app's bundle ID and reads the version field from the JSON response. On Android it queries the Google Play store page and parses the current version from the HTML. Both checks are performed over HTTPS; no API key is required.

The local version is read from PackageInfo.fromPlatform(), which returns the value of version from your pubspec.yaml. Version comparison uses semantic versioning: 1.0.0 < 1.0.1 < 1.1.0 < 2.0.0.

Custom version source

For enterprise apps not published on a public store, implement UpgraderStore and return the latest version from your own endpoint:

class MyStore implements UpgraderStore {
  @override
  Future<UpgraderVersionInfo> getVersionInfo({
    required UpgraderState state,
    required Version installedVersion,
    required String? country,
    required String? language,
  }) async {
    final latest = await fetchLatestVersionFromServer();
    return UpgraderVersionInfo(
      appStoreVersion: Version.parse(latest),
      appStoreListingURL: 'https://example.com/download',
    );
  }
}

Then pass it to the constructor:

UpgradeAlert(
  upgrader: Upgrader(
    storeController: UpgraderStoreController(
      onAndroid: () => MyStore(),
      oniOS: () => MyStore(),
    ),
  ),
  child: MyHomePage(),
)

Key Upgrader Configuration Options

Pass an Upgrader() instance to UpgradeAlert to customise behaviour. The most commonly adjusted options are listed below:

Force-update example

To block users from continuing without updating — for example after a breaking API change — set canDismissDialog: false and daysUntilAlertAgain: 0:

UpgradeAlert(
  upgrader: Upgrader(
    minAppVersion: '2.0.0',
    daysUntilAlertAgain: 0,
    canDismissDialog: false,
  ),
  child: MyHomePage(),
)

Users on versions below 2.0.0 see the dialog immediately and cannot close it. Users already on 2.0.0 or higher are unaffected.

Platforms the Upgrader Package Supports

upgrader works across all Flutter target platforms. Store-based version lookup is available where a public store listing exists; other platforms use a custom version source.

Frequently Asked Questions about the Upgrader Package

flutter pub add upgrader

home: UpgradeAlert(child: MyHomePage())