Skip to content

Percentage-Based Rollouts

A percentage rollout offers a patch to a share of the devices on its track, such as 10% of the devices on stable. Raise the share as you gain confidence in the patch, up to 100%. If the patch misbehaves, roll it back. Shorebird picks the devices when they check for patches, so your app needs no extra code.

  • Rollouts need Shorebird 1.6.139 or newer. Run shorebird upgrade to get it.
  • Only releases built with Flutter 3.35.7 or newer take part. Devices on a release built with an older Flutter are outside every rollout below 100%; they get the patch once it reaches 100%. See How devices are chosen.
  • Rollouts work on every plan.

Pass --rollout with the percentage when you publish the patch:

shorebird patch android --release-version 1.0.0+1 --track stable --rollout 10

Without --rollout, a patch goes to every device on its track. Run shorebird patch --help for the values --rollout accepts.

shorebird patches promote and shorebird patches set-track take --rollout too. Moving a patch onto a track starts a new rollout there, so you can test a patch on staging and then promote it to 10% of stable:

shorebird patches promote --release-version 1.0.0+1 --patch-number 1 --rollout 10

Moving a patch to another track with Change track in the Shorebird Console puts it on that track at 100%. The Console doesn’t set or show rollout percentages; use the CLI or the API.

shorebird patches list and shorebird patches info show a patch that’s partway through its rollout next to its track, such as stable (10%).

shorebird patches rollout --release-version 1.0.0+1 --patch-number 1 --percentage 50

Raise it to 100 to offer the patch to every device on its track. You need the same permission as for moving the patch onto its track.

A rollout only goes up: shorebird patches rollout refuses a lower percentage. Devices that got the patch keep getting it as you raise the percentage. For a patch that’s already on its track, use shorebird patches rollout, not promote.

When you patch several platforms at once, such as shorebird patch --platforms=android,ios, each platform’s patch gets its own number and its own rollout. shorebird patch prints the shorebird patches rollout command for each; raise each one by its number.

The CLI can’t lower a rollout. Leaving the percentage where it is holds the rollout at that share: devices outside it keep getting what they had, the newest patch on the track that’s at 100%. To stop serving the patch at all, roll it back.

If the patch is broken, roll it back. Devices that installed it remove it on their next check. The Rolling out card in Mission Control doesn’t look at rollout percentages: a stable patch at 10% can show there, with its Roll back button, like any other. See Roll back from the rollout card for which patch the card shows.

Each install of your app has an anonymous install identifier, which the updater sends with each patch check. Shorebird hashes it with the patch to put the install at a fixed position from 0 to 100%. A patch at 10% is offered to the installs whose position is below 10%.

  • The position doesn’t change, so an install in the rollout stays in it as you raise the percentage.
  • Each patch has its own positions. An install in the first 10% of one patch’s rollout may be outside the next patch’s.
  • The identifier is per install. Uninstalling the app or clearing its data gives the next install a new identifier, and so a new position.
  • An install outside a rollout gets the newest patch for its platform on its track that’s at 100%, or no patch if there isn’t one. When several patches are rolling out on the same track, an install gets the newest one it’s in.
  • A rollout reaches no one if its patch is numbered below a patch for the same platform that’s at 100% on the same track, since the newer patch outranks it.
  • Releases built with a Flutter version older than 3.35.7 send no identifier, so their devices are outside every rollout below 100%.

The percentage is of the installs that check that track, so 10% on stable is 10% of the devices on stable, not of every device.

To see what share of devices run the patch, run:

shorebird metrics adoption --release-version 1.0.0+1

It shows, for each patch, the share of the release’s devices running that patch or a later one. It needs Shorebird 1.6.129 or newer; see Metrics commands.

In the Shorebird Console, when the Rolling out card at the top of Mission Control shows your patch, it counts the devices running that patch or a later one, out of the release’s devices on the patch’s platform, not only the ones in the rollout. The count needs a release built with Flutter 3.47.4 or newer, since older releases don’t report which patch a device is running. On an older release the card says Rollout adoption needs Flutter 3.47.4+ instead. The card moves on to a newer patch or release, and shrinks to a Last shipped line a week after the patch was created or once 80% of those devices have it (when the card shows the count); see Roll back from the rollout card. To follow a longer rollout, use shorebird metrics adoption.

For a patch’s downloads and installs, open the release and go to its Insights tab. Patch activity charts each patch’s downloads and installs over time, and All-time installs totals the installs per patch. These count download and install events, so a device that reinstalls the app counts again; they aren’t a count of devices.

On a protected track, each step of a rollout needs approval. Publishing or promoting a patch to the track with --rollout files an approval request at that percentage. shorebird patches rollout is refused there: to raise the percentage, promote the patch to the track again at the new percentage, which files a new request. The CLI refuses to promote a patch to the track it’s already on, so send that request with shorebird api. It answers 409 with patch_approval_required and a link to the request, which means the request was filed; running it again replaces that request:

shorebird api -X POST /apps/APP_ID/patches/promote \
  -F patch_id=PATCH_ID -F channel_id=CHANNEL_ID -F rollout_percentage=50

PATCH_ID and CHANNEL_ID are IDs, not the patch number or the track’s name. shorebird patches info prints a patch’s ID, and shorebird api /apps/APP_ID/channels lists the tracks’ IDs.

During a deployment freeze, putting any patch on stable and raising a rollout on it are refused unless you override the freeze.

Raise a rollout with PUT /apps/{appId}/releases/{releaseId}/patches/{patchId}/rollout and a body such as {"rollout_percentage": 50}. The promote endpoint, POST /apps/{appId}/patches/promote, takes rollout_percentage too. The rollout endpoint is marked unstable in the spec, since its shape may change. List release IDs with shorebird api /apps/APP_ID/releases, and see the API reference.

On Enterprise, both endpoints also take a timed schedule in rollout_steps: 2 to 10 rising percentages ending at 100, each step but the last with a duration_minutes to hold before the next. Shorebird raises the rollout at each step, and can pause over weekends with rollout_pause_weekends and rollout_timezone.

You can also run a rollout yourself, by choosing a track in your app’s code. This helps when you need to reach releases built with a Flutter version older than 3.35.7, or to lower a rollout, which the CLI can’t do. Otherwise, use --rollout.

The sample code for this approach is at https://github.com/shorebirdtech/samples/tree/main/progressive_rollout_demo

It has three parts:

  1. Using Shorebird’s “tracks” feature to publish patches to different sets of users.
  2. Using a cloud key-value (KV) store to manage rollout percentages for each release version.
  3. Randomly assigning every device a “group number” between 1 and 100. If a device’s group number is less than or equal to the current rollout percentage for the current app version, that user will get the partially rolled-out (“beta”) patch. Otherwise, the user will receive the stable patch.

If you haven’t already, run Shorebird init in your Flutter project to add Shorebird to your app.

This feature also requires v2.0.0 of package:shorebird_code_push. You can add this to your project using flutter pub add shorebird_code_push or by adding it to your pubspec.yaml manually.

You will need to update your shorebird.yaml to tell Shorebird you want to manage your own updates (see auto_update):

app_id: your-app-id-here

# Add this line. Setting auto_update to false tells Shorebird not to check
# for stable track updates on app launch

auto_update: false

Do this by assigning each user a number between 1 and 100 and saving that value to a local cache using package:shared_preferences:

Future<int> getGroupNumber() async {
  final prefs = await SharedPreferences.getInstance();
  final cachedGroupNumber = prefs.getInt(groupKey);
  if (cachedGroupNumber != null) return cachedGroupNumber;
  final groupNumber = Random().nextInt(100) + 1;
  await prefs.setInt(groupKey, groupNumber);
  return groupNumber;
}

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final groupNumber = await getGroupNumber();
  runApp(MyApp(groupNumber: groupNumber));
}

This guide uses Firebase’s Cloud Firestore to create a simple key-value pairing of release versions to rollout percentages, although any method of retrieving a rollout percentage from the cloud will work.

Future<int?> _fetchRolloutPercentage() async {
  final collection = await FirebaseFirestore.instance
    .collection(firestoreCollectionName)
    .get();
  if (collection.docs.isEmpty) return null;
  final releaseVersion = await _releaseVersion();
  return collection.docs.first.data()[releaseVersion] as int?;
}

Now, tie this all together by using the group number and the rollout percentage to decide whether a user should get patches in the beta track or in the stable track.

Future<UpdateTrack> _updateTrack() async {
  final rolloutPercentage = await _fetchRolloutPercentage();

  // If no rollout percentage is set for this version, default to stable.
  if (rolloutPercentage == null) return UpdateTrack.stable;

  // If the user's group number is less than or equal to the rollout
  // percentage, they are on the beta track. For example:
  // - if the rollout percentage is 25%, users with group numbers 1-25
  //   are on the beta track, and the other 75% are on the stable track.
  // - if the rollout percentage is 100%, all users are on the beta track.
  return widget.groupNumber <= rolloutPercentage
      ? UpdateTrack.beta
      : UpdateTrack.stable;
}

Pass the track to both checkForUpdate and update:

Future<void> _checkForUpdate() async {
  final track = await _updateTrack();
  final status = await _updater.checkForUpdate(track: track);
  if (status == UpdateStatus.outdated) {
    await _updater.update(track: track);
  }
}

_updater is a ShorebirdUpdater(). The sample app calls _checkForUpdate() from a button. In your app, call it each time the app starts, without awaiting it, so the device keeps checking the track its group belongs to. With auto_update: false, this call is also how devices learn that a patch was rolled back, so make it early in startup; see Update strategies. update() throws an UpdateException when the update fails; see When update() throws.

So that the patch is easy to spot, first change the seedColor in main.dart from Colors.deepPurple to Colors.red. Then create a release for Android:

shorebird release android

This will create a release build of your app (an aab file) that is patchable with Shorebird. You will distribute this build to your users the same way you distribute your apps today.

Now, launch the example using shorebird preview, which downloads the release and runs it on a local device:

Release build showing group number 76 with a red background

This screenshot shows that the device is in group 76. This means that it will request patches on the stable track until the rollout percentage is >= 76, at which point it will start requesting patches in the beta track.

Because a patch hasn’t been created on the beta track or a rollout percentage set yet, there isn’t much to see yet.

Change the seedColor back to Colors.deepPurple and create a patch on the beta track using the following command:

shorebird patch android --track=beta

And update the rollout percentage in Firebase:

Cloud Firestore showing 1.0.0+1 at 50% rollout

Press the update button, and the Shorebird preview output shows the following (formatted for readability):

11-13 15:54:06.188 1854 1943 I flutter : updater::network:
  [shorebird] Sending patch check request:
  app_id: fdd48b3f-0b05-41b0-ac22-464600f739ee, channel: stable,
  release_version: 1.0.0+1, platform: android, arch: aarch64,
  current_patch_number: None

Now, change the rollout percentage in Firebase to 76%:

Cloud Firestore showing 1.0.0+1 at 76% rollout

Press the update button again, and you’ll now see:

11-13 16:41:42.525 7036 7102 I flutter : updater::network:
  [shorebird] Sending patch check request:
  app_id: fdd48b3f-0b05-41b0-ac22-464600f739ee, channel: beta,
  release_version: 1.0.0+1, platform: android, arch: aarch64,
  current_patch_number: None

11-13 16:41:42.666 7036 7102 I flutter : updater::updater:
  [shorebird] Patch check response: PatchCheckResponse {
    patch_available: true,
    patch: Some(Patch {
      number: 1,
      hash: "6baa53e40fe1ef0d1230c0ab04ef9dacc7fb5d19368278f2cb2b09a333fdd0c2",
      download_url: "https://cdn-dev.shorebird.cloud/api/v1/patches/fdd48b3f-0b05-41b0-ac22-464600f739ee/android/aarch64/3098/dlc.vmcode",
      hash_signature: None
    }),
    rolled_back_patch_numbers: Some([])
  }

11-13 16:41:43.279 7036 7102 I flutter : updater::updater:
  [shorebird] Patch 1 successfully downloaded. It will be launched when the app next restarts.

Note that the channel field in the patch check request has changed from stable to beta, and that the patch has been downloaded.

Patched build showing group number 76 with a purple background

Once the patch has reached 100% and you’re happy with it, promote it to stable:

shorebird patches promote --release-version 1.0.0+1 --patch-number 1

Devices checking stable now get it, including new installs. Promoting moves the patch off beta, and a device that asks for a track with no patch keeps the patch it has, so devices that already run it keep running it. Then remove the release’s rollout percentage, so every device checks stable again. For how promotion works, see Promoting a patch between tracks.

The Rolling out card in Mission Control doesn’t show a patch while it’s on beta. Once it’s on stable, the card can show it with a count of devices updated; see Roll back from the rollout card for which rollout the card shows. The card’s week counts from when the patch was created, so a patch that spent more than a week on beta shows only as a Last shipped line.

To stop more devices getting the patch, set the release’s rollout percentage to 0. Devices then check stable again. What a device that already installed the patch runs after that is covered in Switching a device between tracks.

If the patch is broken, roll it back as well. A rollback applies to the patch on every track, so devices that installed it remove it on their next check, whichever track they ask for.