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.

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.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:

<resources>
    <color name="ic_launcher_background">#38735D</color>
</resources>

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

   <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>

3. 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.

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.

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.