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
// 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.
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")
}
}
}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"]
}
}
}| Command | Result |
|---|---|
overlayFilter(file("example-custom/launcherOverlay/beta.png")) |
 |
| Filter | Command | Result |
|---|---|---|
| Gray ribbon | grayRibbonFilter() |
 |
| Green ribbon | greenRibbonFilter() |
 |
| Yellow ribbon | yellowRibbonFilter() |
 |
| Orange ribbon | orangeRibbonFilter() |
 |
| Red ribbon | redRibbonFilter() |
 |
| Blue ribbon | blueRibbonFilter() |
 |
| 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.
| 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) |
 |
defaultFlavorNaming: use flavor name in default ribbons, instead of using buildTypeenable: enable/disable all filters for a flavor/type/variantproductFlavors: 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
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)
easylauncher/ - source code of Gradle plugin
sample/ - root directory of supported Android applications which serve as test projects
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.