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
Our percentage-based rollout system will have the following three parts:
- Using Shorebird’s “tracks” feature to publish patches to different sets of users.
- Using a cloud key-value (KV) store to manage rollout percentages for each release version.
- 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:
We do this by assigning each user a number between 1 and 100 and saving that
value to a local cache using
package:shared_preferences
:
We’ve used 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.
We can 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.
We’ll start by creating a release for 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, we’ll launch our example using shorebird preview
, which downloads the
release and runs it on a local device:
We can see from this screenshot that our device is in group 76. This means that we will request patches on the stable track until our rollout percentage is >= 76, at which point we will start requesting patches in the beta track.
Because we haven’t created a patch on the beta track or set a rollout percentage yet, there isn’t much to see yet.
Let’s change the background color from Colors.deepPurple
to Colors.red
and
create a patch on the beta track using the following command:
And update the rollout percentage in Firebase:
Press the update button, and our shorebird preview output shows the following (formatted for readability):
Now if we change the rollout percentage in Firebase to 76%:
And press the update button again, we will now see:
Note that the channel field in the patch check request has changed from stable to beta, and that we’ve downloaded our patch.