Update strategies

When your app looks for patches, and when it starts using them.

The default: automatic

With nothing configured, the app checks for a patch in the background every time it starts. A new patch downloads quietly and is used from the next start. Users never see a screen change in front of them, and never wait for a download.

Checking when you choose

Turn the automatic check off in overpush.yaml, then release again:

auto_update: false

From that release on, the app never checks by itself. It looks for a patch only when your code calls OverPush.update(), for example right after login or from a settings screen:

import 'package:overpush/overpush.dart';

final status = await OverPush.update();
switch (status) {
  // updated  → a patch was downloaded; it runs from the next app start
  // upToDate → nothing newer
  // revoked  → the running patch was pulled; the next start runs the store build
  // failed   → no network, or the check didn't complete; nothing changed
}

If a check is already running, update() waits for it instead of starting a second one. It works with auto_update on too.

Asking users to restart

A downloaded patch runs from the next start. If a fix matters right away, show your own message when update() returns updated, asking the user to close and reopen the app.

Which patch is running

Tag analytics or crash reports with the patch the app is running:

final int? patch = await OverPush.currentPatchNumber(); // null = the store build

Or just whether any patch is in effect:

if (OverPush.isPatched) { /* running a patch, not the store build */ }

Showing an update in your own UI

OverPush shows nothing on screen. If you want to tell users about an update, listen to OverPush.events and design it your way: a banner, a progress bar, a dialog. The same events arrive on Android and iOS, for the automatic check and for update().

OverPush.events.listen((event) {
  switch (event) {
    case OverPushChecking():
      // a check with the server started
    case OverPushPatchFound(:final patchNumber):
      // a new patch exists and is about to download
    case OverPushDownloading(:final percent):
      // downloading: percent is 0–100 (null if the size is unknown)
    case OverPushPatchReady(:final patchNumber):
      // downloaded and verified; it runs from the next app start
    case OverPushUpToDate():
      // nothing new
    case OverPushRevoked():
      // the running patch was pulled; the next start runs the store build
    case OverPushFailed(:final error):
      // no network, or the patch didn't verify; nothing changed
  }
});

A screen that opens after an event fired can read OverPush.lastEvent to catch up.

Want a complete, ready-to-copy banner? See Show updates in your app.

What's next