Android Flavors
This guide will walk through how to setup an app in which there are 2 deployment flavors: internal
and stable
. It will cover how to validate a patch on the internal flavor and then promote the patch to the stable flavor on Android.
This guide assumes the Shorebird command-line is installed on your machine and that you are logged into an account. Refer to the getting started instructions for more information.
In this guide, we’ll go through the process of creating a new project from scratch. To apply these changes to an existing project, skip this step and read ahead.
Create a new project using flutter create flavors
.
Next, edit the android/app/build.gradle
to contain two productFlavors:
Lastly, edit android/app/src/main/AndroidManifest.xml
to use the applicationLabel
so that we can differentiate the two apps easily:
To learn more about configuring productFlavors
refer to the Android Developer documentation.
Next, initialize Shorebird in the current project via shorebird init
.
The generated shorebird.yaml
should look something like:
Because the project contains flavors, shorebird init
generates an app per flavor and you can validate the release flavor by visiting Shorebird console.
Now that we’ve created our apps on shorebird, we need to create releases (one for each flavor). To create a release, we’ll use the shorebird release android
command.
We can verify the releases were created successfully by visiting Shorebird console.
Next, preview the app release locally on a device or emulator, use shorebird preview
.
This will download the releases and run them on your device.
In addition to previewing the releases locally, you should also submit the generated app bundles to the Play Store. In this case, both apps can be part of the internal test flavor and only the stable variant should be promoted to production.
- The
internal
variant should only be used for internal testing/validation. - The
stable
variant should be shipped to end users in production.
Now that we have our internal and stable releases on the Play Store, we can create a patch using shorebird patch android
. For the sake of this example, let’s adjust the app theme to use deepOrange
as the seed color in lib/main.dart
:
Typically shorebird patch
should be used to fix critical bugs.
Now that we’ve applied the changes, let’s patch the internal
variant:
We can validate the patch by visiting Shorebird console then select the internal release or re-launching the internal release.
The first time the app is re-launched, we should still see the purple theme and shorebird will detect and install the patch in the background. Kill and re-launch the app a second time to see the applied patch.
If all went well, you should see the patch was applied after re-launching the app a second time. All devices that have the internal variant of the app installed should also receive the patch 🎉
Once you have validated the patch internally, you can promote the patch to the stable variant via:
At this point, you have a setup which allows you to push patches to internal testers before promoting them to production 🎉
The full source code for this example can be found here.
If you want to add a new flavor to your project after initializing Shorebird, you can do so by following the same steps as before.
In build.gradle:
Add this to your shorebird.yaml
by running shorebird init
:
The resulting shorebird yaml: