Requirements for Chromium PWA Install Prompts

This article outlines the specific technical and user-engagement criteria a website must fulfill before a Chromium-based web browser will trigger an installation prompt for a Progressive Web App (PWA). By meeting these foundational requirements—which cover network security, Web App Manifest configurations, Service Worker implementation, and user interaction heuristics—developers can allow users to seamlessly install their web applications directly onto their desktop or mobile devices.

1. Secure Network Connection (HTTPS)

The website must be served over a secure network connection using HTTPS. Chromium browsers require a secure context to ensure the integrity of the application and protect user data. The only exception to this rule is during local development, where localhost is considered a secure origin.

2. A Valid Web App Manifest

The website must include a linked Web App Manifest file (typically manifest.json or manifest.webmanifest) in the HTML head. For Chromium to consider the PWA installable, this JSON file must include the following specific properties:

  • name or short_name: At least one of these properties must be provided. They are used to display the app's name on the install prompt and the user's home screen or desktop.
  • icons: Must contain an array of image objects. At a minimum, you must provide both a 192x192 pixel icon and a 512x512 pixel icon.
  • start_url: Defines the URL that loads when a user launches the installed application.
  • display: Determines the browser UI shown when the app is launched. The value must be set to fullscreen, standalone, minimal-ui, or window-controls-overlay. Using browser will not trigger the install prompt.
  • prefer_related_applications: This property must either be omitted entirely or explicitly set to false. If set to true, the browser assumes you want the user to install a native platform app (like an Android app from the Play Store) instead of the PWA.

3. Service Worker Registration

The website must register a Service Worker with a scope that matches or encompasses the start_url defined in the manifest. Furthermore, the Service Worker must include a fetch event handler. This proves to the browser that the application is capable of managing network requests and potentially functioning offline, which is a core tenet of a Progressive Web App.

4. User Engagement Heuristics

Chromium will not immediately bombard a first-time visitor with an install prompt, even if all technical requirements are met. The user must demonstrate a baseline level of engagement with the site:

  • The user must have interacted with the domain for at least 30 seconds.
  • The user must have clicked or tapped on the page at least once during their visit.

5. Installation State

Finally, the Progressive Web App must not already be installed on the user's device. If Chromium detects that the PWA is currently installed, it will suppress the beforeinstallprompt event and hide the installation UI options in the address bar and browser menu.