Your PWA looks wrong on Android

The icon in a white circle

Android crops icons into an adaptive shape, and it only does so when a manifest icon declares "purpose": "maskable". Without one, Chrome refuses to crop and centres your square PNG on a white circle instead.

We read the manifests of 386 apps in this directory: 215 of the 373 readable ones declare no maskable icon — 58%. It is the most common defect in the whole ecosystem, and it takes one extra PNG to fix.

The WebAPK that will not update

When Chrome installs a PWA on Android it generates a real Android package — a WebAPK — with your name, icon and theme baked in at install time. Change any of them and the installed users keep the old version until Chrome regenerates the package, which it does on its own schedule, typically within a few days but not on demand.

So an icon that looks wrong right after a deploy is often not wrong; it is old. Confirm by installing fresh on a clean device before rewriting anything.

Installed, then empty

Android's install criteria only require a service worker with a fetch handler. They do not require it to cache anything. So an app can pass every check, install perfectly, and open blank the first time the user has no signal.

This is the failure we find most often when we measure: 235 of 386 installable apps show nothing with the network cut. The four causes are here, and the diagnosis takes under a minute in devtools.

The prompt that never comes

If Chrome never offers to install, one of the installability conditions is unmet and the browser says nothing. Application → Manifest → Installability names it directly. The two we see fail most are a missing 512px icon and a worker without a fetch handler — the full checklist.

A quieter version also exists: without a screenshots array Android shows the minimal install sheet instead of the richer dialog. 331 of the 373 manifests we read declare none, so most apps are being offered in their least persuasive form.

Frequently asked