Easylauncher Gradle Plugin for Android

Modify the launcher icon of each of your app-variants using simple Gradle rules. Add ribbons of any color, overlay your own images, customize it according to your needs!

Circle	RoundedRectangle	Teardrop

This library heavily relies on the original Akaita's easylauncher plugin, but introduces supports for modern build tools and Vector icons

Usage

Basic usage

// in app/build.gradle
plugins {
    id "com.starter.easylauncher" version "${{version}}"
}

see Gradle Plugin Portal for the details

What should I do if I get `Could not resolve all artifacts` error?

In some configurations a dependency resolution error might be thrown with a message:

Could not find com.android.tools.build:gradle:x.x.x`.

As a solution apply the plugin to the root project using:

// in root project's build.gradle 
buildscript {
    repositories.google()
}
plugins {
    id "com.starter.easylauncher" version "${{version}}" apply false
}

then apply the plugin in your application module:

// in app/build.gradle 
plugins {
    id "com.starter.easylauncher"
}

Alternatively, if using Version Catalog:

[plugins]
starter-easylauncher = { id = "com.starter.easylauncher", version.ref = "easylauncher" }

See related issue for more information.

Advanced usage

By default, the plugin applies green ribbon for all debuggable build variants. You can customize the filters applied to each type, flavor and variant of your app.

Imagine these are the type and flavors of your app:

// in app/build.gradle
android {
    buildTypes {
        named("debug") {
            //Debuggable, will get a default ribbon in the launcher icon
        }
        named("release") {
            //Non-debuggable, will not get any default ribbon
        }
        register("beta") {
            //Debuggable, will get a default ribbon in the launcher icon
            debuggable true
        }
        register('canary') {
            //Non-debuggable, will not get any default ribbon
            debuggable false
        }
    }
    productFlavors {
        register("local") {}
        register("qa") {}
        register("staging") {}
        register("production") {}
    }
}

You could customize the plugin's behaviour like this:

easylauncher {
    defaultFlavorNaming = true // Use flavor name for default ribbon, instead of the type name
    showWarnings = true // Defines if the plugins should show warnings at configuration time
    
    productFlavors {
        register("local") {}
        register("qa") {
            // Add one more filter to all `qa` variants
            filters redRibbonFilter()
        }
        register("staging") {}
        register("production") {}
    }
    
    buildTypes {
        register("beta") {
            // Add two more filters to all `beta` variants
            filters = [
                    customRibbon(ribbonColor: "#0000FF"),
                    overlayFilter(file("example-custom/launcherOverlay/beta.png"))
            ]
        }
        register("canary") {
            // Remove ALL filters to `canary` variants
            enable = false
        }
        register("release") {}
    }
    
    variants {
        register("productionDebug") {
            // OVERRIDE all previous filters defined for `productionDebug` variant
            filters = orangeRibbonFilter("custom")
        }
    }
}

Providing Icon Names

By default, the plugin automatically discovers launcher icon and applies provided filters.
Custom icon names, useful i.e. when defining multiple activity aliases, can be provided using iconNames property as follows:

easylauncher {
    iconNames = ["@mipmap/custom_launcher_icon"] // optional, disables automatic launcher icon discovery and will use provided icons only

    buildTypes {
        register("beta") {
            // icon names can also be provided per each configuration (buildType, productFlavor or variant)
            iconNames = ["@mipmap/beta_launcher"]  
        }
    }
}

Available filters

Overlay filter

Command	Result
`overlayFilter(file("example-custom/launcherOverlay/beta.png"))`

Ribbon filters

Filter	Command	Result
Gray ribbon	`grayRibbonFilter()`
Green ribbon	`greenRibbonFilter()`
Yellow ribbon	`yellowRibbonFilter()`
Orange ribbon	`orangeRibbonFilter()`
Red ribbon	`redRibbonFilter()`
Blue ribbon	`blueRibbonFilter()`

Advanced Ribbon filter

Description	Command	Result
Custom background color	`customRibbon(ribbonColor: "#6600CC")`
Custom label	`customRibbon(label: "label", ribbonColor: "#DCDCDC")`
Custom text color	`customRibbon(label: "label", ribbonColor: "#DCDCDC", labelColor: "#000000")`
Custom gravity - Top	`customRibbon(label: "custom", position: "top")`
Custom gravity - Bottom	`customRibbon(position: "bottom")`
Custom gravity - TopLeft	`customRibbon(position: "topLeft")`
Custom gravity - TopRight	`customRibbon(position: "topRight")`
Custom text size (relative to the icon size)	`customRibbon(position: "bottom", textSizeRatio: 0.2)`
Custom font (locally installed)	`customRibbon(position: "top", font: "ComicSansMs")`
Custom font (using font pack)	`customRibbon(position: "top", font: file("fonts/CustomFont.ttf"))`

Troubleshooting on "Problem reading font data."

When using docker or a minimalistic environment one might encounter above error message when loading Fonts.
The solution is to make sure font support was installed i.e. by calling:

apk add --no-cache freetype fontconfig ttf-dejavu

See related issue for more information.

Chrome-like filters

Filter	Command	Result
Default	`chromeLike()`
Custom appearance	`chromeLike(label: "Custom", ribbonColor: "#FF00FF", labelColor: "#FFFFFF")`
Custom font (locally installed)	`chromeLike(label: "Custom", font: "ComicSansMS-Bold")`
Custom gravity - Top (with additional padding)	`chromeLike(label: "Top", gravity: "Top", labelPadding: 10)`
Custom overlay/label alignment	`chromeLike(label: "Tall", overlayHeight: 0.6, textSizeRatio: 0.3)`

Available options

defaultFlavorNaming: use flavor name in default ribbons, instead of using buildType
enable: enable/disable all filters for a flavor/type/variant
productFlavors: define filters for flavors (will be added to filters defined for types)
buildTypes: define filters for types (will be added to filter defined for flavors)
variants: define filters for variants (will override any other filters)
iconNames: provides a list of icons which will have the filters applied

Requirements

Minimal requirements for the plugin are:

Gradle: 8.2.1
Android Gradle Plugin: 8.2.2
Java Version: 11
minSdkVersion: 26 (theoretically there should be no lower boundary - it just hasn't been tested)

Project Structure

easylauncher/   - source code of Gradle plugin
sample/         - root directory of supported Android applications which serve as test projects

Credits

Credits to Akaita's easylauncher plugin which this project heavily relies on

YourKit supports open source projects with innovative and intelligent tools for monitoring and profiling Java and .NET applications. YourKit is the creator of YourKit Java Profiler, YourKit .NET Profiler, and YourKit YouMonitor.

usefulness / easylauncher-gradle-plugin