Percentage-Based Rollouts

This guide describes how you can implement a percentage-based patch rollout system using predefined tracks.

The sample code for this guide can by found at https://github.com/shorebirdtech/samples/tree/main/progressive_rollout_demo

This percentage-based rollout system 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.

Add Shorebird to your app

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

Add the shorebird_code_push package

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:

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

Add logic to bucket your users

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));
}

Add logic to determine rollout percentage

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?;
}

Use these values to choose a track

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;
}

Seeing it in action

Start by creating 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:

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 background color from Colors.deepPurple to Colors.red and create a patch on the beta track using the following command:

shorebird patch android --track=beta

And update the rollout percentage in Firebase:

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: PatchCheckRequest {
    app_id: "fdd48b3f-0b05-41b0-ac22-464600f739ee",
    channel: "stable",
    release_version: "1.0.0+1",
    platform: "android",
    arch: "aarch64"
  }

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

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: PatchCheckRequest {
    app_id: "fdd48b3f-0b05-41b0-ac22-464600f739ee",
    channel: "beta",
    release_version: "1.0.0+1",
    platform: "android",
    arch: "aarch64"
  }

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.