firebase_remote_update 0.2.1

Reusable force/optional update gate for Flutter apps, backed by Firebase Remote Config and guarded by a real store-availability check (Play In-App Update on Android, iTunes lookup on iOS) so users are [...]

firebase_remote_update

A small, reusable force/optional update gate for Flutter apps.

• Policy source: Firebase Remote Config (per-platform min & recommended versions, a global kill switch, an emergency override, and an optional message).
• Safety gate: before forcing, it verifies the target build is actually available on the store — Play In-App Update on Android, iTunes lookup on iOS — so users are never locked out of a build that isn't live yet.
• Fails open: any error (no network, bad config, throttled fetch) results in no forced update.

Why

The classic force-update bug is flipping the minimum version before the matching build is approved/rolled out, which locks users out with no installable update. This module gates the force on real store availability to prevent that, while still allowing a deliberate emergency lockout.

Usage

import 'package:firebase_remote_update/firebase_remote_update.dart';

const config = AppUpdateConfig(
  androidPackageId: 'com.xxx.xxxxxxx',
  iosAppStoreId: 'xxxxxxxxxxx',
  storeCountry: 'xx',
);

final service = AppUpdateService(config: config); // uses FirebaseRemoteConfig.instance

// Wrap your app (non-blocking — app renders immediately, evaluation runs in
// the background):
UpdateGate(
  service: service,
  forcedBuilder: (context, decision) => MyUpdateScreen(service: service, decision: decision),
  child: myHome,
);

// Or use blocking mode (app hidden behind a loading screen until the decision
// is resolved):
UpdateGate(
  service: service,
  mode: UpdateGateMode.blocking,
  loadingBuilder: (context) => MyLoadingScreen(),
  forcedBuilder: (context, decision) => MyUpdateScreen(service: service, decision: decision),
  child: myHome,
);

Call service.startUpdate() from the update screen's button.

Modes

Mode	Behavior	When to use
nonBlocking (default)	App renders immediately. If the result is forced, the gate swaps to forcedBuilder after evaluation.	Most apps — fastest perceived startup.
blocking	App is hidden behind loadingBuilder until the decision is resolved.	When you need the decision before any UI is visible (e.g. to avoid a flash of the main screen before a forced update).

Remote Config parameters

Key	Type	Default	Meaning
force_update_enabled	bool	false	Global kill switch for forced updates.
min_required_version_android / _ios	string	0.0.0	Force below this version.
recommended_version_android / _ios	string	0.0.0	Soft prompt below this version.
force_ignore_store_check	bool	false	Emergency: force even if the build isn't on the store yet.
update_message	string	''	Optional message shown on the update screen.

Parameter names are configurable via RemoteConfigKeys.

Version string parsing

The iOS store check reads the version field from the public iTunes lookup API (https://itunes.apple.com/lookup?id=<appStoreId>&country=<cc>). That field is the hand-written marketing version from App Store Connect — not the build number, which the public API does not expose.

Since 0.2.1 the parser is tolerant: it finds the dotted version anywhere in the string and ignores the text around it. 1.4.9 (149), 149 1.4.9, v1.4.9, release 1.4.9 build 149, and 1.4.9+149 all parse as 1.4.9. Two rules protect users from bad input:

• Two or more dotted versions in one string (e.g. 1.4.9 requires iOS 15.6) are ambiguous → the parser returns null and the gate fails open.
• A string with no dotted version parses only if it is a pure bare integer (2 → 2.0.0); everything else → null → fail open.

Recommendation for releases: still enter a clean major.minor.patch version string (e.g. 1.5.0) in App Store Connect. Do not append the build number — apps that ship with a pre-0.2.1 version of this package cannot parse the suffix, and their store gate silently stops forcing updates.

Reuse in another app

Supply a different AppUpdateConfig. No code changes. Add it to your pubspec.yaml:

dependencies:
  firebase_remote_update: ^0.2.0

Or via git:

dependencies:
  firebase_remote_update:
    git:
      url: https://github.com/rachadaccoumeh/firebase_remote_update.git
      ref: v0.2.0