How WebAPKs change PWA installation on Android

When a user installs a Progressive Web App on Android, Chrome does more than create a home screen shortcut. It generates a dedicated Android application package, known as a WebAPK, and installs it on the device. This gives the PWA a presence in the app launcher and Android's app settings, and lets it register intent filters for URL handling.

Chrome builds the WebAPK from your web app manifest and other metadata. If the manifest changes, Chrome must generate a new APK to reflect those updates.

Intent filters and app scope

Installation via a WebAPK lets your PWA register intent filters for every URL inside its scope. When a user taps a link that falls within that scope, Android opens your standalone PWA instead of a browser tab.

Take a manifest that declares a start_url on the site root:

"start_url": "/",
"display": "standalone",

Launching the installed app opens https://example.com/ as a standalone experience with no browser chrome. The generated WebAPK declares intent filters that match that behavior:

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data
    android:scheme="https"
    android:host="example.com"
    android:pathPrefix="/" />
</intent-filter>

A link to https://example.com/read from any other app would therefore be intercepted by this filter and open inside the PWA.

Restricting URLs with scope

Your PWA does not have to claim every URL on your domain. Adding the scope property to the manifest limits intent handling to URLs matching the origin plus the scope path. This is useful when your domain hosts both the app and other, non-app content that should stay in the browser.

Consider a scope set to /app/:

"scope": "/app/",
"start_url": "/app/",
"display": "standalone",

Opening the app from the launcher goes to https://example.com/app/ standalone. The manifest inside the resultant WebAPK will set an android:pathPrefix that mirrors that restriction:

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data
    android:scheme="https"
    android:host="example.com"
    android:pathPrefix="/app/" />
</intent-filter>

The practical effect:

  • Handled by the app: https://example.com/app/ and https://example.com/app/read/book
  • Opened in the browser: https://example.com/help/ and https://example.com/about/

Permissions, storage and state

Despite being installed as an APK, the PWA is still a web app in how it handles permissions. You cannot request permissions at install time. Ask for them at runtime, and only when a feature is actually needed—for instance, defer the camera prompt until the user tries to take a photo.

Data is not walled off. Chrome stores the installed app's data in the same profile that serves the browser, so cookies and client-side storage are shared and the service worker remains active. Anything the app stores, the browser can access, and vice versa.

This means clearing Chrome's cache will also clear the installed site's local data.

Updating the WebAPK

Details on how Chrome refreshes a WebAPK after manifest changes now live in How Chrome handles updates to the web app manifest.

WebAPK questions, answered

Splash screen icons

Provide icons at both 192px and 512px for best splash screen results. WebAPKs built with Chrome 71 or later display a larger splash icon automatically when those sizes are present.

Installing alongside a native app

Users can install your site independently of any native Android app. If you expect both to be installed, differentiate your PWA's icon or name so users can tell them apart.

Device migration and re-installation

Installed PWAs do not yet follow a user to a new Android device automatically. The Chrome team considers this an important area and is exploring how to support it.

Permission prompts

Permissions remain a Chrome-managed feature. Users see Chrome's prompt, not Android's, and can modify permissions later in Chrome's settings.

Android version support

Any Android version that runs Chrome for Android supports PWA installation—that includes Jelly Bean and later.

WebView and browser engines

WebAPKs do not use the WebView. The site runs in the same version of Chrome that was active when the user installed it.

Play Store and other browsers

Generated WebAPKs are not uploadable or listed on the Play Store. To distribute your own APK, look into Trusted Web Activities. For other Android browsers seeking the same install flow, the Chrome team is working to make the capability available across browsers.