Adriana Jara on web.dev

How to add Richer Install UI

2023-03-27T00:00:00Z

App stores provide a space for developers to showcase their apps before installation, with screenshots and text information that help the user make the choice to install the app. Richer install UI provides a similar space for web app developers to invite their users to install their app, directly from the browser. This enhanced UI is available in Chrome for Android and desktop environments.

Default prompt #

See the example below for the default experience, which doesn’t provide enough context.

Default install dialog on desktop

Default install dialog on mobile

Richer Install UI #

To get the Richer Install UI dialog instead of the regular small default prompt, add screenshots and description fields to your web manifest. Check out the Squoosh.app example below:

Richer installation UI on desktop and mobile.

The Richer Install UI dialog is composed of the contents of the description and screenshots fields in the web manifest.

To trigger the dialog you just need to add at least one screenshot for the corresponding form factor, but it is recommended to add the description as well. Checkout the specifics for those fields below.

Screenshots #

Screenshots really add the 'richer' part to the new install UI and we strongly recommend their use. In your manifest you add the screenshots member, which takes an array that requires at least one image and Chrome will display up to eight. An example is shown below.

 "screenshots": [
    {
     "src": "source/image1.gif",
      "sizes": "640x320",
      "type": "image/gif",
      "form_factor": "wide",
      "label": "Wonder Widgets"
    }
]

Screenshots must follow these criteria:

Width and height must be at least 320px and at most 3,840px.
The maximum dimension can't be more than 2.3 times as long as the minimum dimension.
All screenshots with the same form factor value must have identical aspect ratios.
Only JPEG and PNG image formats are supported.
Only eight screenshots will be shown. If more are added, the user agent simply ignores them.

Also, you need to include the size and type of the image so it renders correctly. See this demo.

The form_factor indicates to the browser whether the screenshot should appear on desktop (wide) or mobile environments (narrow).

Description #

The description member describes the application in the installation prompt, to invite the user to keep the app.

The dialog would display even without a description, but it is encouraged. There is a maximum that kicks in after 7 lines of text (roughly 324 characters) and longer descriptions are truncated and an ellipsis is appended (as you can see in this example).

{
…
"description": "Compress and compare images with different codecs
right in your browser."
}

Description added.

Longer descriptions are truncated.

The description appears at the top of the installation prompt.

You may have noticed from the screenshots that installation dialogs also list the app's origin. Origins that are too long to fit the UI are truncated, this is also known as eliding and is used as a security measure to protect users.

Demo #

How Chrome handles updates to the web app manifest

2020-10-14T00:00:00Z

When a PWA is installed, the browser uses information from the web app manifest for the app name, the icons the app should use, and the URL that should be opened when the app is launched. But what if you need to update app shortcuts or try a new theme color? When and how are those changes reflected in the browser?

In most cases, changes should be reflected within a day or two of the PWA being launched, after the manifest has been updated.

Updates on desktop Chrome #

When the PWA is launched, or opened in a browser tab, Chrome determines the last time the local manifest was checked for changes. If the manifest hasn't been checked since the browser last started, or it hasn't been checked in the last 24 hours, Chrome will make a network request for the manifest, then compare it against the local copy.

If select properties in the manifest have changed (see list below), Chrome queues the new manifest, and after all windows have been closed, installs it. Once installed, all fields from the new manifest (except name, short_name, and icons) are updated.

Which properties will trigger an update? #

display (see below)
scope
shortcuts
start_url
theme_color
file_handlers

What happens when the `display` field is updated? #

If you update your app's display mode from browser to standalone your existing users will not have their apps open in a window after updating. There are two display settings for a web app, the one from the manifest (that you control) and a window/browser tab setting controlled by the user. The user preference is always respected.

Testing manifest updates #

The chrome://web-app-internals page (available in Chrome 85 or later), includes detailed information about all of the PWAs installed on the device, and can help you understand when the manifest was last updated, how often it's updated, and more.

To manually force Chrome to check for an updated manifest, you can either launch Chrome with the command line flag --disable-manifest-update-throttle or restart Chrome (use about://restart), this resets the timer so that Chrome will check for an updated manifest when the PWA is next launched. Then launch the PWA. After closing the PWA, it should be updated with the new manifest properties.

References #

Updatable Web Manifest Fields

Updates on Chrome for Android #

When the PWA is launched, Chrome determines the last time the local manifest was checked for changes. If the manifest hasn't been checked in the last 24 hours, Chrome will schedule a network request for the manifest, then compare it against the local copy.

If select properties in the manifest have changed (see list below), Chrome queues the new manifest, and after all windows of the PWA have been closed, the device is plugged in, and connected to WiFi, Chrome requests an updated WebAPK from the server. Once updated, all fields from the new manifest are used.

Which properties will trigger an update? #

background_color
display
orientation
scope
shortcuts
start_url
theme_color
web_share_target

If Chrome is unable to get an updated manifest from the server, it may increase the time between checks to 30 days.

Testing manifest updates #

The about://webapks page includes detailed information about all of the PWAs installed on the device, and can tell you when the manifest was last updated, how often it's updated, and more.

To manually schedule an update to the manifest, overriding the timer and local manifest do the following:

Plug in the device and ensure it's connected to WiFi.
Use the Android task manager to shut down the PWA, then use the App panel in Android settings to force stop the PWA.
In Chrome, open about://webapks and click the "Update" button for the PWA. "Update Status" should change to "Pending".
Launch the PWA, and verify it's loaded properly.
Use the Android task manager to shut down the PWA, then use the App panel in Android settings to force stop the PWA.

The PWA usually updates within a few minutes, once the update has completed, "Update Status" should change to "Successful"

References #

UpdateReason enum for Chrome on Android

Adriana Jara on web.dev

How to add Richer Install UI

Default prompt #

Richer Install UI #

Screenshots #

Description #

Further reading #

Demo #

How Chrome handles updates to the web app manifest

Updates on desktop Chrome #

Which properties will trigger an update? #

What happens when the display field is updated? #

Testing manifest updates #

References #

Updates on Chrome for Android #

Which properties will trigger an update? #

Testing manifest updates #

References #

What happens when the `display` field is updated? #