Gradle power – android product flavours and configuration

Product Flavours have been around for quite some time now. I feel Product flavours are one of the coolest things about android studio. I am so smitten by product flavour that I decided to write a post about it :p. What follows will be introduction, application, grouping, filtering and configuration of product flavours in android. If you have already applied these and have any questions, shoot in comments below.

Product flavours are very useful when you want to create multiple versions of your app like demo, free, paid etc. You must have seen various versions of same app in google play like angry birds free and angry birds hd. You can have a single source code and generate n number of variants of your app. If you want to write common code that can be used in various types of apps, product flavours is not the way to go, what you are looking for is android library.

Let’s see how to create product flavours

android {...
    defaultConfig {...}
    productFlavors {
        flavour1 {...}
        flavour2 {...}
        flavour3 {...}
    }
    ...
    buildTypes{...}
}

As you can see, this skeleton goes in android block in build.gradle file (app/module level). By writing this we have created 3 flavours called flavour1, flavour2 and flavour3 (duh..). By default android has 2 debug types called debug and release (more can be added like jnidebug), a build variant or variant is a combination of build type and product flavour. So now there will be 6 build variants. flavour1-debug, flavour1-release, flavour2-debug, flavour2-release, flavour3-debug and flavour3-release. Inside these flavour blocks are flavour specific properties and methods like applicationId (the app package name), versionCode, buildConfigField etc. We will see these a little later. Click here to see ProductFlavour DSL (domain specific language) object that is used to configure flavour specific properties and methods.

We all know about default config. Whatever properties and methods that are defined in default config are inherited by all product flavours. Default config block is also uses ProductFlavour DSL (domain specific language) object. This means that everything that goes inside a default config block can go inside a flavour block. Each product flavour can override the properties and methods defined in default config block.

android {...
    defaultConfig {
        applicationId "the.default.packagename"
        minSdkVersion 8
        versionCode 10
    }
    productFlavors {
        flavour1 {
            applicationId "the.default.packagename.flavour1"
            minSdkVersion 15
        }
        flavour2 {
            applicationId "the.default.packagename.flavour2"
            versionCode 20
        }
        flavour3 {...}
    }
    ...
    buildTypes{...}
}

In the above example some properties are overwritten and rest are inherited from default config block. Click here to see list of all the properties and methods that can be configured inside default config and flavour block (or groovy closure). ApplicationId property is to assign different default package to each flavour. This makes sure that different variants of your app can be installed on the same device.

SourceSets for product flavours

This creates 6 source sets:

"src/flavour1" - android.sourceSets.flavour1
"src/flavour2" - android.sourceSets.flavour2
"src/flavour3" - android.sourceSets.flavour3
"src/androidTestFlavour1" - android.sourceSets.androidTestFlavour1
"src/androidTestFlavour2" - android.sourceSets.androidTestFlavour2
"src/androidTestFlavour3" - android.sourceSets.androidTestFlavour3

// All these folder follow the java/src/main/.. structure 
// for any flavour and test specific customization. click 
// below link to know more about android sourceSets.
// http://goo.gl/NvAg74

This flavour specific folder structure is where the flavour specific code resides. Like flavour1 customization must be done inside “src/flavour1/ {java, res, assets}” folder. The common code lives in “src/main/…” directory. If you want to change the app name for say flavour2, all you need to do is define app_name (or whichever string resource you are using as app name in manifest) in “src/flavour2/res/values/strings.xml“. Just whatever you want to override, do not copy the entire xml or res file in flavour specific folder, let android resource merger do its job. Say you are using “@drawable/ico_app or @mipmap/ico_app” as app icon, this can be easily configured for each flavour by keeping flavour specific icons in respective folder structure. e.g. for flavour3, just name the flavour3 specific icon as ico_app and keep it in drawable or mipmap folder (whichever you are using) in flavour3 specific directory.

Multi-flavour variants

Now this is useful when the variants of your app is decided by one dimension. e.g. say the dimension is price, you can create flavours like free, paid, freemium etc. what if the requirement is to create variants based on multiple dimensions, like for environment dimension there can be three flavours “dev“, “staging” and “production“, and three for price dimension “free“, “freemium” and “paid“, and may be another dimension. In this case you can select either of the six flavours plus debug or release. But the product flavour we are interested in is dependent on both dimensions. Something like free-dev-debug, paid-production-release etc. Here we are trying to group product flavours, which is not allowed by default. This can be enabled via dimension attribute of product flavours. We can set dimensions of product flavours via flavorDimensions attribute of android block, and then we can assign a dimension to each flavour. Here is an example:

android {...
    flavorDimensions "country", "price"
    productFlavors {
        free {dimension "type"...}
        pro {dimension "type"...}
        India {dimension "country"...}
        China {dimension "country"...}
        Russia {dimension "country"...}
    }
    ...
    buildTypes{...}
}

In this example as we can see there are two flavour dimensions, country and price. Country flavour dimension has three flavours India, China and Russia, price has two flavours free and pro. This in turn creates 12 build variants for us:

India-free-debug
India-free-release
India-pro-debug
India-pro-release
China-free-debug
China-free-release
China-pro-debug
China-pro-release
Russia-free-debug
Russia-free-release
Russia-pro-debug
Russia-pro-release

As you can see just by defining the flavorDimensions and dimension attribute, the product flavours can be grouped, and android creates variants that are all possible combinations of flavours of all types of dimensions and build types. These variants are reflected everywhere, including the build variants tab on lower left side of android studio.

Filtering product flavours

Now look at the list of build variants above. What if we want to filter this list. Say I don’t want Russia-free and India-paid variant for some reason. This is possible by ignoring some of the build variants based on some condition. Below is an example of ignoring Russia-free variant.

//Filtering variants
android {
...
    variantFilter { variant ->
        def names = variant.flavors*.name
        def buildTypeName = variant.buildType.name
        // if buildtype is required for filtering use
        // the above field
        if (names.contains("Russia") && names.contains("free")) {
            variant.ignore = true
            // or variant.setIgnore(true)
        }
    }
    ...
}

The build variants can be ignored by setting the ignore field or by setting setIgnore to false. This global filtering is reflected everywhere including the build variants tab on lower left side of android studio, assemble, install tasks etc.

Flavour specific dependency

You must have seen testCompile “junit…” in your projects. This is flavour specific dependency. junit for example is a testing library and must not be shipped with the release apk (why increase the size of your apk with something that is required only for testing). Adding “flavourCompile” syntax dependency section of app level build.gradle adds the dependency for that particular flavour. If you are familiar with facebook’s stetho library, then you know it is only for development purpose and must not be shipped with release version. This is an awesome feature that comes with android product flavours. Some examples:

testCompile 'junit:junit:4.12'
stethoFlavourCompile 'com.facebook.stetho:stetho:1.3.1'

There are a couple of things to discuss before we can conclude product flavours.

BuildConfig constants and res values

Now we know that flavour specific code goes in flavour specific sourceSet, but sometimes we need flavour specific code in main code base (“src/main/…“). The problem here is: the main source code doesn’t know which flavour is or will be getting generated. For this there is something called BuildConfig. It is an auto generated file and must not be tempered with. This file contains flavours specific constants and can be used in main source code. Check out  ProductFlavour DSL object for available properties and methods. You can set flavour specific constants and resources like this:

android {...
    flavorDimensions "country", "price"
    productFlavors {
        free {dimension "type"
            buildConfigField("String", "featureList", "restricted")
            resValue("boolean", "ads", "true")
        ...}
        pro {dimension "type"
            buildConfigField("String", "featureList", "all")
            resValue("boolean", "ads", "false")
        ...}
       India { applicationId "my.app.india"
            dimension "country"
            buildConfigField("String", "shortcode", "IN")
       ...}
       China { applicationId "my.app.china"
            dimension "country"
            buildConfigField("String", "shortcode", "CHN")
       ...}
       Russia { applicationId "my.app.russia"
            dimension "country"
            buildConfigField("String", "shortcode", "RU")
       ...}
    }
    ...
    buildTypes{...}
}

This is then used to generate BuildConfig class and dynamic resources (check our resources in generated folder). For a Russian-pro-debug build variant (from flavour definition above), the generated build config will look something this:

//Build config for Russia-pro-debug build variant
public final class BuildConfig {
    public static final boolean DEBUG = Boolean.parseBoolean("true");
    public static final String APPLICATION_ID = "my.app.russia";
    public static final String BUILD_TYPE = "debug";
    public static final String FLAVOR = "proRussia";
    public static final int VERSION_CODE = 1;
    public static final String VERSION_NAME = "1.0";
    public static final String FLAVOR_price = "pro";
    public static final String FLAVOR_country = "Russia";
    // Fields from product flavor: pro
    public static final String featureList = "all";
    // Fields from product flavor: Russia
    public static final String shortcode = "RU";
}

As you can see the constants are specific to a selected flavour. This can then be used in the main source. Easy peasy isn’t it? Build config file is in this location (“<app or module>\build\generated\source\buildConfig\<variant>\<debug or release>\my\app\package“).

Dynamic manifest

Sometimes we need to use app’s package in manifest file. But with product flavours the app’s package or application id is no longer fixed. In this case we can make the package dynamic in manifest with groovy syntax. By doing so, the application Id is picked from build.gradle at run time. Here is a sample:

<manifest xmlns:android="http://schemas.android.com/apk/res/android......
...
<permission 
    android:name="${applicationId}.permission.C2D_MESSAGE"
    android:protectionLevel="signature" />
...
<application...

This is an example for a declared permission for android GCM. Notice the groovy syntax around applicationId, that is where the magic is happening.

Let me know what you think. Happy coding!!!

Have questions? Did I miss anything? Shoot below in comments.

-Kaushal D (@drulabs twitter/github)

drulabs@gmail.com