---
title: Migrate the Android launcher icon to an adaptive icon
slug: configured-commerce/docs/migrate-the-android-launcher-icon-to-an-adaptive-icon
docTags:
createdAt: 2026-08-09T15:34:49.000Z
---
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](https://developer.android.com/develop/ui/views/launch/icon_design_adaptive) 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:
```text
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.png
```
### Define 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`:
```xml
#38735D
```
**Background image**
1. Add `ic_launcher_background.png` to each `mipmap-*` density folder.
2. Reference the image as `@mipmap/ic_launcher_background` when you create the adaptive icon definitions.
### Create the adaptive icon definitions
1. Create the folder `android/app/src/main/res/mipmap-anydpi-v26/`.
2. Add `ic_launcher.xml` to the folder with the following contents:
```xml
```
1. 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.:
```xml
```
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.
1. Uninstall any existing copy of the app from the device or emulator.
2. Run `flutter clean`.
3. Run `flutter pub get`.
4. 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.
1. Open the launcher on a device or emulator running Android 8.0 or later.
2. Confirm the icon masks correctly in round, squircle, and rounded-square shapes.
3. Confirm the icon displays correctly in the launcher, app drawer, Settings, and recent apps.
4. (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 `` 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.