Version Enforcement

Set a minimum required app version per environment. Force users to update immediately or prompt them softly — without shipping a new build.

Why version enforcement matters

Mobile apps have long tails of old versions. After a breaking API change, a security fix, or a critical bug fix, you need a way to ensure users upgrade without waiting for organic App Store update adoption.

Koolbase lets you set a minimum version from the dashboard. Users below that version see either a mandatory update screen (force update) or a dismissible prompt (soft update) — no code change or new release required.

Update modes

force_updateForce Update

The app is blocked. The user must update before they can continue. Use for breaking API changes or critical security patches.

soft_updateSoft Update

A dismissible prompt is shown. The user can continue using the app but is encouraged to update. Use for non-critical improvements.

up_to_dateUp to Date

The user's version meets or exceeds the minimum. No update UI is shown.

Check version on startup

Call Koolbase.version.check() after init, before showing your app. The SDK reads the current app version from package_info_plus automatically.

lib/main.dartDart

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Koolbase.init(apiKey: 'pk_live_...');

  final versionCheck = await Koolbase.version.check();

  switch (versionCheck.status) {
    case VersionStatus.forceUpdate:
      runApp(ForceUpdateApp(
        message: versionCheck.message ?? 'Please update to continue.',
        storeUrl: versionCheck.storeUrl,
      ));
      return;

    case VersionStatus.softUpdate:
      // Show the app but display a dismissible update banner
      runApp(MyApp(showUpdateBanner: true, updateMessage: versionCheck.message));
      return;

    case VersionStatus.upToDate:
      runApp(const MyApp());
  }
}

Force update screen example

lib/force_update_screen.dartDart

class ForceUpdateApp extends StatelessWidget {
  final String message;
  final String? storeUrl;

  const ForceUpdateApp({required this.message, this.storeUrl, super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: Center(
          child: Padding(
            padding: const EdgeInsets.all(32),
            child: Column(
              mainAxisAlignment: MainAxisAlignment.center,
              children: [
                const Icon(Icons.system_update, size: 64, color: Colors.blue),
                const SizedBox(height: 24),
                Text(message, textAlign: TextAlign.center),
                const SizedBox(height: 32),
                if (storeUrl != null)
                  ElevatedButton(
                    onPressed: () => launchUrl(Uri.parse(storeUrl!)),
                    child: const Text('Update Now'),
                  ),
              ],
            ),
          ),
        ),
      ),
    );
  }
}

Setting the version policy

Navigate to your project → Version Policy. Set the minimum version, update mode, message, and store URL per environment.

Minimum versione.g. 2.1.0 — users below this version see the update UI

Update modeforce_update or soft_update

MessageCustom message shown to users who need to update

Store URLApp Store or Play Store link for the update button

Version comparison uses semver

Versions are compared as semver strings — 2.1.0 > 2.0.9 > 1.99.0. Make sure your app version in pubspec.yaml follows semver format (major.minor.patch).