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.

Prerequisites

This guide assumes the Patchwing command-line is installed on your machine and that you are logged into an account. Refer to the getting started instructions for more information.

Create a Project

Note

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 patchwing create flavors.

Configure Flavors

Kotlin DSL

Next edit the android/app/build.gradle.kts to contain two productFlavors:

defaultConfig {
    ...
}

+    flavorDimensions += "track"
+    productFlavors {
+        create("internal") {
+            dimension = "track"
+            applicationIdSuffix = ".internal"
+            manifestPlaceholders["applicationLabel"] = "[Internal] Patchwing Example"
+        }
+        create("stable") {
+            dimension = "track"
+            manifestPlaceholders["applicationLabel"] = "Patchwing Example"
+        }
+    }

buildTypes {
  ...
}

Groovy DSL

Next edit the android/app/build.gradle to contain two productFlavors:

defaultConfig {
    ...
}

+    flavorDimensions "track"
+    productFlavors {
+        internal {
+            dimension "track"
+            applicationIdSuffix ".internal"
+            manifestPlaceholders = [applicationLabel: "[Internal] Patchwing Example"]
+        }
+        stable {
+            dimension "track"
+            manifestPlaceholders = [applicationLabel: "Patchwing Example"]
+        }
+    }

buildTypes {
  ...
}

Caution

The applicationIdSuffix property is optional. If you use services that depend on a consistent package name (e.g., Firebase), removing applicationIdSuffix may be necessary to avoid configuration issues.

Lastly, edit android/app/src/main/AndroidManifest.xml to use the applicationLabel so that we can differentiate the two apps easily:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
-  <application android:label="flavors" android:name="${applicationName}" android:icon="@mipmap/ic_launcher">
+  <application android:label="${applicationLabel}" android:name="${applicationName}" android:icon="@mipmap/ic_launcher">

Note

To learn more about configuring productFlavors refer to the Android Developer documentation.

Re-initialize Patchwing

Next, re-initialize Patchwing in the current project via patchwing init --force to update the YAML file.

patchwing init --force

The generated patchwing.yaml should look something like:

# This file is used to configure the Patchwing updater used by your application.
# Learn more at https://patchwing.net
# This file should be checked into version control.

# This is the unique identifier assigned to your app.
# It is used by your app to request the correct patches from Patchwing servers.
app_id: ee322dc4-3dc2-4324-90a9-04c40a62ae76
flavors:
  internal: ee322dc4-3dc2-4324-90a9-04c40a62ae76
  stable: 904bd3d5-3526-4c1c-a832-7ac23c95302d

Because the project contains flavors, patchwing init now generates an app per flavor and you can validate the release flavor by visiting Patchwing console.

Create a release

Now that we’ve created our apps on patchwing, we need to create releases (one for each flavor). To create a release, we’ll use the patchwing release android command.

# Create a release for the internal flavor
patchwing release android --flavor internal

# Create a release for the stable flavor
patchwing release android --flavor stable

We can verify the releases were created successfully by visiting Patchwing console.

Preview the release

Next, preview the app release locally on a device or emulator, use patchwing preview.

# Preview the release for the internal flavor.
patchwing preview --app-id ee322dc4-3dc2-4324-90a9-04c40a62ae76 --release-version 1.0.0+1

# Preview the release for the stable flavor.
patchwing preview --app-id 904bd3d5-3526-4c1c-a832-7ac23c95302d --release-version 1.0.0+1

Note

--app-id and --release-version are optional parameters. If not provided, you will be prompted to select the app and release version interactively.

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.

Note

• The internal variant should only be used for internal testing/validation.
• The stable variant should be shipped to end users in production.

Creating a patch

Now that we have our internal and stable releases on the Play Store, we can create a patch using patchwing 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:

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        // This is the theme of your application.
        //
        // TRY THIS: Try running your application with "flutter run". You'll see
        // the application has a blue toolbar. Then, without quitting the app,
        // try changing the seedColor in the colorScheme below to Colors.green
        // and then invoke "hot reload" (save your changes or press the "hot
        // reload" button in a Flutter-supported IDE, or press "r" if you used
        // the command line to start the app).
        //
        // Notice that the counter didn't reset back to zero; the application
        // state is not lost during the reload. To reset the state, use hot
        // restart instead.
        //
        // This works for code too, not just values: Most code changes can be
        // tested with just a hot reload.
-        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
+        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepOrange),
        useMaterial3: true,
      ),
      home: const MyHomePage(title: 'Flutter Demo Home Page'),
    );
  }
}

Note

Typically patchwing patch should be used to fix critical bugs.

Now that we’ve applied the changes, let’s patch the internal variant:

patchwing patch android --flavor internal

We can validate the patch by visiting Patchwing console then select the internal release or re-launching the internal release.

Note

If you are testing locally, you don’t need to re-run patchwing preview – just re-launch the app from the device or emulator directly.

The first time the app is re-launched, we should still see the purple theme and patchwing 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 🎉

Promote the patch

Once you have validated the patch internally, you can promote the patch to the stable variant via:

patchwing patch android --flavor stable

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.

Adding new flavors

If you want to add a new flavor to your project after initializing Patchwing, you can do so by following the same steps as before.

In build.gradle:

defaultConfig {
    ...
}

    flavorDimensions "track"
    productFlavors {
        internal {
            dimension "track"
            applicationIdSuffix ".internal"
            manifestPlaceholders = [applicationLabel: "[Internal] Patchwing Example"]
        }
+       beta {
+           dimension "track"
+           applicationIdSuffix ".beta"
+           manifestPlaceholders = [applicationLabel: "[Beta] Patchwing Example"]
+       }
        stable {
            dimension "track"
            manifestPlaceholders = [applicationLabel: "Patchwing Example"]
        }
    }

buildTypes {
  ...
}

Add this to your patchwing.yaml by running patchwing init:

$ patchwing init
✓ Detecting product flavors (0.6s)
New flavors detected: beta
✓ Fetching apps (0.1s)
✓ Flavors added to patchwing.yaml (0.2s)

The resulting patchwing yaml:

app_id: ee322dc4-3dc2-4324-90a9-04c40a62ae76
flavors:
  internal: ee322dc4-3dc2-4324-90a9-04c40a62ae76
  stable: 904bd3d5-3526-4c1c-a832-7ac23c95302d
+ beta: a41f8226-4b46-45d6-9e19-b14d0cf17bdc