You spend weeks building your Cordova app. You test it on your own device, it looks great, and you upload it to the Play Store. Then a tester on a Pixel sends you a screenshot, and your carefully designed icon is sitting inside a circle with the corners chopped off. The logo that took hours to perfect is now a clipped mess. If that story sounds familiar, you have just met Android’s adaptive icon system, and it has been waiting to catch you off guard.
What You Need to Know Before You Build
Android’s adaptive icon system requires a design approach that most web developers never encounter until their first Play Store submission.
- Android crops your icon into whatever shape the launcher chooses, so your core artwork must stay within the inner 80% of the canvas to avoid being clipped.
- The maskable icon format tells the system exactly which region of the image is safe to display, making your icon launcher-proof across all Android devices.
- Cordova needs both a standard icon fallback and a foreground layer entry in config.xml to generate the correct adaptive icon files at build time.
What Android’s Adaptive Icon System Actually Does to Your Image
Before Android 8.0 Oreo, every launcher displayed your icon as a plain square. Life was simple. Then Google introduced adaptive icons, and the rules changed completely.
An adaptive icon is built from two layers. There is a background layer, which sits behind everything and is usually a solid color or a subtle pattern. Then there is a foreground layer, which holds your actual logo or artwork. The Android launcher takes those two layers and applies a mask on top. That mask is determined by the device manufacturer and the launcher installed on the phone. On a Pixel, you get circles. On a Samsung, you might get squircles. On a OnePlus, rounded squares. The launcher picks the shape. You do not.
This is where things go sideways for Cordova developers. If you supply a single flat PNG without any awareness of how Android will crop it, the launcher applies its mask to whatever it finds. If your logo sits close to any edge of that PNG, the mask cuts right into it. Google’s adaptive icon design specification defines the full-bleed canvas as 108x108dp, with a safe visible zone of 72dp centered in the middle. That leaves 18dp of bleed on every side. That bleed region exists so launchers can animate and parallax the icon layers. Your artwork cannot stray into that area and expect to survive every mask shape.
The Safe Zone Rules That Govern Every Adaptive Icon
The web platform addressed this problem with the maskable icon format, which is part of the Web App Manifest specification. A maskable icon is a regular image designed with a specific safe zone in mind. The entire image canvas is used, but only the central 80% is guaranteed to remain visible after any mask is applied. That central region is called the safe zone.
The rule is simple in principle. Imagine a circle centered in your image, with a diameter equal to 80% of the shorter side. Every part of your logo, wordmark, or meaningful visual content must stay inside that circle. The outer edges of the image exist purely as background fill. They will get clipped on some devices. Treat them like bleed in print design. They need to be there, but nothing critical can live there.
For a 512×512 source image, the safe zone circle has a diameter of roughly 410 pixels. That is a comfortable working area in the center, but it is easy to misjudge when working in a design tool without a visible guide overlay. The background fill matters too. Transparent backgrounds fail on adaptive icons. Android expects the background layer to be fully opaque. A PNG with a transparent outer region either picks up the app’s theme color or renders something unexpected depending on the device. Always use a solid, opaque background that covers the entire canvas.
Building Your Maskable Icon Asset Before Touching Any Config
You need a single source image that is at least 512×512 pixels, has your logo centered within the safe zone, and has an opaque background covering every pixel of the canvas. If your current icon is just a logo on a transparent background, you need to rebuild it before going any further.
Start in your design tool. Create a 512×512 artboard. Place a solid background that fills the entire canvas. Then draw or paste your logo in the center, keeping all meaningful elements within that central 80% zone. Leave a comfortable margin inside the safe zone boundary rather than pressing right up against it. Export as a flat PNG at the full 512×512 size.
To check whether your icon will survive Android’s masking, run it through a maskable icon generator that previews how your image looks under circle, squircle, and rounded-square masks. That preview step catches safe zone violations before they reach a real device. Do not skip it. If your logo is getting clipped in the preview, go back and scale it down or shift it toward the center. The constraint feels tight at first, but the payoff is an icon that reads correctly on every Android launcher regardless of manufacturer.
Adding the Correct Entries to config.xml
Cordova reads your icon configuration from config.xml, and the entries needed for Android adaptive icons differ from the basic icon entry you might already have in place.
For a standard fallback, you still need the classic entry pointing to a square PNG in your res folder. That covers older Android versions and non-adaptive launchers. For adaptive support, you add a foreground entry that Cordova uses to generate the foreground layer of the adaptive icon. The background attribute on that entry tells Android what color to render behind it.
<platform name="android">
<icon src="res/android/icon.png" />
<icon
src="res/android/icon-foreground.png"
foreground="res/android/icon-foreground.png"
background="#1565c0" />
</platform>The background attribute accepts either a hex color string or a path to a background PNG. Using a solid hex color is the most reliable approach for most apps. It guarantees the background layer is always opaque and exactly the color you intended. If you use a background image, confirm it tiles cleanly and has no transparency anywhere.
The foreground PNG you reference here should be your full 512×512 image with the logo centered in the safe zone. Cordova’s Android platform tooling resizes it into the multiple density buckets Android expects during the build process.
Placing Files in the platforms/android Directory
Cordova generates and manages the platforms/android directory during the build, but you can also inspect icon files there manually to confirm everything landed correctly. When you run cordova prepare android, Cordova copies your icon resources into the correct mipmap directories under platforms/android/app/src/main/res.
The mipmap directories follow Android’s density naming convention. Each one holds a version of your icon at a specific pixel density. Cordova handles the resizing automatically from your source PNG as long as the source is at least 192×192 pixels. A 512×512 source image gives plenty of headroom and produces clean results at all target sizes.
Android Icon Sizes by Density Bucket
| Density | Directory | Standard Icon (px) | Adaptive Layer (px) |
|---|---|---|---|
| mdpi | mipmap-mdpi | 48×48 | 108×108 |
| hdpi | mipmap-hdpi | 72×72 | 162×162 |
| xhdpi | mipmap-xhdpi | 96×96 | 216×216 |
| xxhdpi | mipmap-xxhdpi | 144×144 | 324×324 |
| xxxhdpi | mipmap-xxxhdpi | 192×192 | 432×432 |
After running cordova prepare android, open the mipmap-anydpi-v26 folder and verify that ic_launcher.xml and ic_launcher_round.xml exist. Each file references your foreground and background layers by drawable name. A mismatch between the XML references and the actual drawable file names produces a white or broken icon at runtime, which is one of the harder icon bugs to diagnose after the fact.
iOS Has Its Own Rules and Will Reject You Just as Fast
Android gets most of the attention in icon conversations, but iOS has its own requirements that will stop a submission cold if they are not met. Apple applies a rounded-square mask automatically and has no foreground/background layer system. Your iOS icon must be a flat, opaque square PNG with no rounded corners and no transparency anywhere. Apple rounds the corners at display time, on its own terms.
For Cordova, iOS icons live under the ios platform directory and are referenced in config.xml under a separate ios platform block. You need icons at multiple sizes to cover the App Store listing, the home screen, Spotlight, and Settings. For a modern iOS submission, the minimum includes a 1024×1024 App Store icon alongside the standard home screen sizes.
The key mistake to avoid is baking your own corner radius into the iOS icon design. If you apply a corner radius in your design tool and Apple applies its own on top, the result is a double-rounded edge that looks odd on every device. Keep the iOS source icon as a clean square and let the operating system handle the shaping entirely.
Clearing Every Icon Check Before the Final Cordova Build
Before you run your production build, set aside fifteen minutes to review your icon assets against a structured checklist. Catching a problem now is far less painful than dealing with it after a Play Store upload or an App Store review rejection.
Start with the Android foreground PNG. Open it and mentally map the 80% safe zone. Your logo should sit entirely within that central region with a comfortable margin on every side. If it touches or crosses the boundary, rebuild the asset before continuing. Then confirm the PNG has no transparency anywhere by checking the alpha channel in your image editor. The entire canvas must be fully opaque.
Next, run cordova prepare android without building and navigate to platforms/android/app/src/main/res/mipmap-anydpi-v26. Open the ic_launcher.xml file and confirm that the layer references match the drawable file names in the adjacent mipmap folders. If the names do not align, the build produces a broken icon without throwing any obvious error during compilation.
After that, install the debug APK on a physical Android device. If your device supports it, go into developer settings and change the launcher icon shape. Flip through circle, squircle, and rounded-square options and watch your icon in each mode. It should look clean in all three. If any shape clips your artwork, tighten the safe zone margin in your source file.
For iOS, open your Xcode project or inspect the generated Assets.xcassets catalog and confirm the 1024×1024 App Store icon slot is filled. Missing icons in the catalog trigger upload errors in App Store Connect that can hold up your submission for hours. Also confirm that no icon slot shows a transparency warning. Any transparent pixel in an iOS icon causes a rejection at review time.
Close out by doing a visual check at small sizes. What looks sharp on an xxhdpi screen can look muddy on an mdpi device if the source image has thin lines or fine detail that does not survive the downscale. If your logo relies on detail that compresses poorly, consider creating a simplified version of the mark for use at smaller densities. The whole review takes about fifteen minutes the first time and becomes second nature after a few release cycles. Build it into your release process and it will never blindside you again.
