This article contains contributions from Jeff Posnick and Peter Kotwicz.
Add to Home Screen on Android does more than just add the Progressive Web App to the users Home Screen. Chrome automatically generates and installs a special APK of your app. We sometimes refer to this as a WebAPK. Being installed via an APK makes it possible for your app to show up in the app launcher, in Android's app settings and to register a set of intent filters.
To generate the WebAPK Chrome looks at the web app manifest and other metadata. When an update to the manifest is detected, Chrome will need to generate a new APK.
Android intent filters
When a Progressive Web App is installed on Android, it will register a set of intent filters for all URLs within the scope of the app. When a user clicks on a link that is within the scope of the app, the app will be opened, rather than opening within a browser tab.
Consider the following partial manifest.json:
"start_url": "/",
"display": "standalone",
When a web app using it is launched from the app launcher, it would open
https://example.com/ as a standalone app, without any browser chrome.
The WebAPK would include the following intent filters:
<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>
If the user clicks on a link within an installed app to
https://example.com/read, it would be caught by the intent and opened
in the Progressive Web App.
Using scope to restrict intent filters
If you don't want your Progressive Web App to handle all URLs within your site,
you can add the scope property to
your web app manifest. The scope property tells Android to only open your web
app if the URL matches the origin + scope. It gives you control over which
URLs will be handled by your app, and which should be opened in the browser.
This is helpful when you have your app and other non-app content on the same
domain.
Consider the following partial manifest.json:
"scope": "/app/",
"start_url": "/",
"display": "standalone",
When launched from the app launcher, it would open https://example.com/app/
as a standalone app, without any browser chrome.
Like before, the generated WebAPK would include an intent filter, but with a
different android:pathPrefix attribute in the APK's AndroidManifest.xml:
<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>
Let's take a look at a few examples:
https://example.com/app/ - within /app/
https://example.com/app/read/book - within /app/
https://example.com/help/ - not in /app/
https://example.com/about/ - not in /app/
See scope for more information about
scope, what happens when you don't set it, and how you can use it to define
the scope of your app.
Managing permissions
Permissions work in the same way as other web apps and cannot be requested at install time. Instead they must be requested at run time, ideally only when you really need them. For example, don't ask for camera permission on first load, but instead wait until the user attempts to take a picture.
Managing storage and app state
Even though the progressive web app is installed via an APK, Chrome uses the current profile to store any data, and it will not be segregated away. This allows a shared experience between the browser and the installed app. Cookies are shared and active, any client side storage is accessible and the service worker is installed and ready to go.
Updating the WebAPK
Chrome will periodically compare the locally installed manifest against a copy of the manifest fetched from the network. If any of the properties in the manifest required to add the PWA to the home screen have changed in the network copy, Chrome will request an updated WebAPK, reflecting those new values.
There are a number of rules that govern how these update checks are triggered:
- Update checks only happen when a WebAPK is launched. Launching Chrome directly will not a trigger an update check for a given WebAPK.
- Chrome checks for updates either every 3 days or every 30 days. Checking for updates every 3 days happens the large majority of the time. It switches to the 30 day interval in unlikely cases where the update server cannot provide an update.
- Clearing Chrome's data (via "CLEAR ALL DATA" in Android settings) resets the update timer.
- Chrome will only update a WebAPK if the Web Manifest URL does not change. If
you change the web page from referencing
<link rel="manifest.json">to reference<link rel="manifest2.json">the WebAPK will no longer update. (Don't do this!) - Chrome will only update a WebAPK if the WebAPK is not running. Moving the WebAPK to the background is not sufficient if it keeps running.
- Only WebAPKs created by an official version of Chrome (Stable/Beta/Dev/Canary)
will be updated. It does not work with Chromium (
org.chromium.chrome). - The update check may be delayed until the device is plugged in and has a WiFi connection.
Here's a hypothetical example of how WebAPK update scheduling works over time:
- January 1: Install WebAPK
- January 1: Launch WebAPK → No update check (0 days have passed)
- January 2: Launch WebAPK → No update check (1 day has passed)
- January 4: Launch Chrome → No update check (Launching Chrome has no effect)
- January 4: Launch WebAPK → Check whether update is needed (3+ days have passed)
- January 6: Clear Chrome's data in Android settings
- January 9: Launch WebAPK → No update check (From Chrome's perspective this is the first WebAPK launch)
- January 12: Launch WebAPK → Check whether update is needed (3+ days have passed)
See
UpdateReason
enum in message WebApk for the reasons a WebAPK may be updated.
Frequently asked questions
- What icons are used to generate the splash screen?
-
We recommend you provide at least two icons:
192px and 512px for the splash screen.
We heard from you that icons on the splash screen were too small. WebAPKs generated in Chrome 71 or later will show a larger icon on the splash screen. No action is required, as long as the recommended icons are provided. - What happens if the user has already installed the native app for the site?
- Like add to home screen today, users will be able to add a site independent of any native apps. If you expect users to potentially install both, we recommend differentiating the icon or name of your site from your native app.
- When a user opens a site installed via improved add to Home screen, will Chrome be running?
- Yes, once the site is opened from the home screen the primary activity is still Chrome. Cookies, permissions, and all other browser state will be shared.
- Will my installed site's storage be cleared if the user clears Chrome's cache?
- Yes.
- Will my app be re-installed when I get a new device?
- Not at this time, but we think it is an important area and we are investigating ways to make it work.
- Will I be able to register to handle custom URL schemes and protocols?
- No.
- How are permissions handled? Will I see the Chrome prompt or Android's?
- Permissions will still be managed through Chrome. Users will see the Chrome prompts to grant permissions and will be able to edit them in Chrome settings.
- What versions of Android will this work on?
- Progressive web apps can be installed on all versions of Android that run Chrome for Android, specifically Jelly Bean and above.
- Does this use the WebView?
- No, the site opens in the version of Chrome the user added the site from.
- Can we upload the APKs that are created to the Play Store?
- No. There is no key signing information supplied to enable you to create your own PWA that can be in the store.
- Are these listed in the Play Store?
- No.
- I am developer of another browser on Android, can I have this seamless install process?
- We are working on it. We are committed to making this available to all browsers on Android and we will have more details soon.