Migrate the Android launcher icon to an adaptive icon
An adaptive icon renders your branded launcher icon correctly on every Android device. Android masks the icon to whatever shape the launcher uses. Migrate to an adaptive icon so your logo stays uncropped and matches the shape conventions of the device.
This guide applies to developers who build a branded Android app on Commerce Mobile UI SDK 4.14.0 and 5.1.0.. It covers the Android launcher icon only. Separate guides cover iOS icons, in-app branding, and theming.
Adaptive icons
Understand how Android assembles an adaptive icon before you replace the assets. The structure determines which files your design team must deliver.
The app icon is the image a user taps on the home screen to open your app. It also displays in the app drawer, Settings, and notifications.
An adaptive icon builds that icon from two layers instead of one flat image:
- Background – A solid brand color or a simple background image that fills the tile.
- Foreground – Your logo or symbol, layered on top.
Android masks the two layers into the shape the device uses: a circle, a rounded square, or a squircle. A squircle is a square with heavily rounded corners. The icon then renders cleanly everywhere without cropping important artwork. A single flat image cannot do this.
Adaptive icons are the Android standard as of Android 8.0 (API 26). Devices earlier than Android 8.0 continue to use the flat image, so existing installations keep working.
Your design team or icon vendor produces the artwork, including dimensions and transparency. Android crops the outer edges of both layers during masking. The logo must sit inside the central safe zone, the area that survives every mask shape. This guide covers how to add the finished assets to the app.
For exact safe-zone measurements and mask geometry, go to Adaptive icons in the Android developer documentation.
Prerequisites
Your design team or icon vendor supplies the artwork. Gather the following before you start:
- Foreground – The file ic_launcher_foreground.png, exported at five density buckets.
- Background – A solid brand color as a hex value, for example #38735D. A background image named ic_launcher_background.png at the same five densities also works.
- (Optional) Legacy fallback images – Refreshed ic_launcher.png and ic_round_launcher.png at five densities, for devices earlier than Android 8.0.
- Repository access – Write access to android/app/src/main/res/ and android/app/src/main/AndroidManifest.xml.
Android selects one icon variant per device based on screen density. Every density bucket in the following table needs its own file.
Density | Folder | Foreground (px) | Legacy icon (px) |
|---|---|---|---|
mdpi | mipmap-mdpi/ | 108 × 108 | 48 × 48 |
hdpi | mipmap-hdpi/ | 162 × 162 | 72 × 72 |
xhdpi | mipmap-xhdpi/ | 216 × 216 | 96 × 96 |
xxhdpi | mipmap-xxhdpi/ | 324 × 324 | 144 × 144 |
xxxhdpi | mipmap-xxxhdpi/ | 432 × 432 | 192 × 192 |
Migrate to an adaptive icon
Complete the following procedures in sequence to replace the flat launcher icon with an adaptive icon. The migration touches Android resource configuration only, so the Flutter and Dart code stays unchanged.
Add the foreground assets
Place each density variant of ic_launcher_foreground.png in its matching folder:
android/app/src/main/res/
mipmap-mdpi/ic_launcher_foreground.png
mipmap-hdpi/ic_launcher_foreground.png
mipmap-xhdpi/ic_launcher_foreground.png
mipmap-xxhdpi/ic_launcher_foreground.png
mipmap-xxxhdpi/ic_launcher_foreground.pngDefine the background
Define the background as a solid color or as an image. Most apps use a solid color. Complete one of the following two options, then continue to the adaptive icon definitions.
Solid color
Create android/app/src/main/res/values/ic_launcher_background.xml and substitute your brand color for #38735D:
<resources>
<color name="ic_launcher_background">#38735D</color>
</resources>Background image
- Add ic_launcher_background.png to each mipmap-* density folder.
- Reference the image as @mipmap/ic_launcher_background when you create the adaptive icon definitions.
Create the adaptive icon definitions
- Create the folder android/app/src/main/res/mipmap-anydpi-v26/.
- Add ic_launcher.xml to the folder with the following contents:
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
<background android:drawable="@color/ic_launcher_background"/>
<foreground android:drawable="@mipmap/ic_launcher_foreground"/>
</adaptive-icon>- Add ic_round_launcher.xml to the folder with the same contents.
When you use a background image instead of a solid color, change @color/ic_launcher_background to @mipmap/ic_launcher_background in both files.
Refresh the legacy fallback images (optional)
Replace the flat ic_launcher.png and ic_round_launcher.png in each density folder with refreshed branded versions. These images display only on devices earlier than Android 8.0.
Manifest references
Commerce Mobile UI SDK version declares both launcher icon attributes in AndroidManifest.xml. The migration requires no manifest change.:
<application
android:icon="@mipmap/ic_launcher"
android:roundIcon="@mipmap/ic_round_launcher">
<!-- Activities and other application elements -->
</application>On Android 8.0 and later, these attributes resolve to the adaptive definitions. On earlier devices, they fall back to the flat images. Confirm that both attributes are present.
Rebuild and reinstall the app
The launcher keeps displaying the cached icon until you remove the app, so start with the uninstall.
- Uninstall any existing copy of the app from the device or emulator.
- Run flutter clean.
- Run flutter pub get.
- Run flutter run, flutter build appbundle, or flutter build apk.
Verify the icon
Confirm the icon renders correctly across launcher shapes and surfaces before you ship the build.
- Open the launcher on a device or emulator running Android 8.0 or later.
- Confirm the icon masks correctly in round, squircle, and rounded-square shapes.
- Confirm the icon displays correctly in the launcher, app drawer, Settings, and recent apps.
- (Optional) Confirm the legacy fallback renders correctly on a device earlier than Android 8.0.
Troubleshoot common issues
Use the following table to resolve the issues that occur most often during the migration.
Symptom | Cause and resolution |
|---|---|
The previous icon still displays | The launcher cached the previous icon. Uninstall the app, run flutter clean, and reinstall. |
The foreground artwork is clipped | The artwork does not respect the safe zone. Ask the designer to export the logo within the central safe area. |
The build reports that ic_launcher_foreground is not found | A density variant is missing. The file must exist in all five mipmap-* folders. |
The build reports that the color ic_launcher_background is not found | The file values/ic_launcher_background.xml is missing or misnamed. |
The background displays as transparent | The <background> element does not reference a valid @color/ or @mipmap/ resource. |
FAQ
The following answers cover the questions implementors ask most often about this migration.
- Is migration mandatory? – No. The flat icon continues to work. Migrate so the icon renders correctly across all launcher shapes and matches Android conventions.
- Does this change the Flutter or Dart code? – No. The migration changes Android resource configuration only.
- What about the themed monochrome icon in Android 13 and later? – A monochrome layer tints the icon to the system wallpaper. The layer is optional and Commerce Mobile UI SDK does not ship it.