Intent to Ship: Web Install API

[Lia Hiscock]

Contact emails

liahi...@microsoft.com, krist...@microsoft.com

Explainer

https://aka.ms/webinstall

Specification

https://wicg.github.io/install-element

Design docs
https://docs.google.com/document/d/12nSXJLm8mW0gWZ_yjlXfrV8r9gwJliVt4WVa-209-KA/edit?tab=t.0

Summary

Triggers a request for the browser to install a web app, given a manifest URL and optional manifest ID. The navigator.install() method enables cross-origin web app installation and provides a better developer experience than handling beforeinstallprompt events. This API is proposed to ship together with the <install> element, a declarative entry point to the same installation capability: https://chromestatus.com/feature/5152834368700416.

 

Enterprises can control this in two ways - (1) Enterprise policy, WebAppInstallByUserEnabled, can disable user web app installs broadly, including installs initiated via navigator.install() and <install>. Or (2) Permissions Policy, web-app-installation, can allow or disallow use of this feature on origins the enterprise controls (for example, internal sites/iframes).

Blink component

Blink>AppManifest

Web Feature ID

navigator-install

Motivation

The web currently lacks the ability for a site to offer installation of a web app identified by a cross-origin manifest. Limited support exists for eligible same-origin web apps via ambient installation affordances and the beforeinstallprompt event. However, the existent browser-provided entry points are difficult for developers to use and users to discover.

 

This capability lets developers distribute web apps across the web without proprietary protocols or platform-specific stores. It brings web app distribution closer to the reach developers expect from other application models while preserving browser-controlled safeguards and explicit user choice.

 

Initial public proposal

https://aka.ms/webinstall

Search tags

web install, install, webappinstallation, webinstallapi

TAG review

https://github.com/w3ctag/design-reviews/issues/1245

 

TAG review status

Issues open

 

Review was requested two months ago with updates addressing concerns raised in the earlier design review: https://github.com/w3ctag/design-reviews/issues/1051. The TAG has not yet provided substantive feedback on the updated API shape or design. A recent TAG meeting agreed to develop a finding about the broader capability of web app installation and prompting. That work remains open, and we will continue participating in it.

 

Origin Trial Name

WebAppInstallation

Chromium Trial Name

WebAppInstallation

Link to origin trial feedback summary

https://docs.google.com/document/d/1B21htNQFmhEhhIpnIU7z_jOeH9wEF1Hz9XSKlMWW3a0/edit?pli=1&tab=t.0 

Origin Trial documentation link

Demos/pwa-install-api/README.md at main · MicrosoftEdge/Demos

WebFeature UseCounter name

WebDXFeature::navigator-install

Risks

 

Interoperability and Compatibility

These are additive entry points to web app installation, a capability browsers already provide through browser-controlled UI. The primary interoperability risk is uneven cross-browser availability rather than conflicting behavior for existing content: other engines have not committed to these entry points, and WebKit opposes site-initiated web app installation.

WebKit opposes these entry points because it considers installation a user decision whose flow should begin in browser UI. We acknowledge this substantive difference in approach. However, origin-trial partners, public developer reports, and standards discussions consistently identified existing web app installation as difficult for users to discover and cumbersome for developers to offer. Developers expressed strong support for a direct and predictable installation path while retaining browser-controlled confirmation UI and existing installability requirements.

 

Our designs preserve browser control over installation through required user activation, explicit consent in browser-controlled UI, and the user agent’s ability to suppress the flow. The <install> element further provides user-agent-controlled rendering. Detailed abuse, privacy, and security protections are described in our explainer and our TAG review request. Given those safeguards and the demonstrated developer and user need, we believe shipping in Chromium is appropriate while standards discussions continue.

 

Gecko: No signal (https://github.com/mozilla/standards-positions/issues/1179)

WebKit: Oppose (https://github.com/WebKit/standards-positions/issues/463)

Web developers: Positive (https://github.com/w3ctag/ethical-web-principles/issues/120#issuecomment-2285348765) https://github.com/w3ctag/ethical-web-principles/issues/120#issuecomment-2285431557

Other signals: pwastore.io - https://www.reddit.com/r/PWA/comments/1o1excp/comment/niit2jh/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button

Ergonomics

This could be used in conjunction with the navigator.getInstalledRelatedApps API, which tells a developer if any related web apps are installed for their site, before attempting to install with navigator.install. There is overlap between navigator.install and the BeforeInstallPrompt event. navigator.install is more ergonomic, and we think developers will prefer its declarative install. See this thread - https://github.com/MicrosoftEdge/MSEdgeExplainers/issues/1055

Activation

No activation risks. It should be relatively easy for developers to take advantage of this feature immediately, as-is. The API was designed with ergonomics in mind, and we have four places with instructions for developers (two test sites, the explainer itself, and a Developer Trial README)

Security

Security considerations - https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/WebInstall/explainer.md#accessibility-privacy-and-security-considerations

WebView application risks

Does this intent deprecate or change behavior of existing APIs, such that it has potentially high risk for Android WebView-based applications?

N/A

 

Debuggability

Existing DevTools support for promise-based JavaScript APIs applies. In addition to the generic DataError rejection, Web Install failures for eligible same-origin manifests are reported in the Issues panel using bounded failure categories, such as manifest fetch or parse failure, invalid start_url, and missing required fields. This provides diagnostics for browser-process manifest fetches that are not visible in the Network panel. Cross-origin and internal failure details are not reported. See Debuggability doc - https://docs.google.com/document/d/1rGvLhD4SR8Y9M1wVmqgyesPNkbZGU7HOqlttjEFJ5Vo/edit?tab=t.i3gxb63o1ngb

Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, ChromeOS, Android, and Android WebView)?

No
Windows, Mac, Linux, and ChromeOS will be shipped first. Android will be supported later, due to significant technical deviation in the web app ecosystem - https://issues.chromium.org/issues/424497410. As of now, no plan to support Android WebView.

Is this feature fully tested by web-platform-tests?

No
The API's shape and activation restrictions are tested - https://wpt.fyi/results/web-install. However, web app installs are currently not supported by automated tests, as they require user interaction to confirm the installation. Manual web app testing instructions can be published.

DevTrial instructions

https://microsoftedge.github.io/Demos/pwa-install-api/

Flag name on about://flags

web-app-installation-api

Finch feature name

WebAppInstallation

Rollout plan

Will ship enabled for all users

Requires code in //chrome?

False

Tracking bug

https://issues.chromium.org/issues/333795265

Launch bug

https://launch.corp.google.com/launch/4495880

Measurement

We have a JavaScript UseCounter and WebDX feature - https://chromestatus.com/metrics/webfeature/timeline/popularity/375 We will also implement chromium UMAs and possibly UKMs for the API service results.

Availability expectation

Feature is available only in Chromium browsers for the foreseeable future.

Adoption expectation

Feature is used by specific partner(s) to provide functionality within 12 months of launch in Chrome.

Adoption plan

We are in communication with partners. We plan to post an update on developer.chrome.com and blogs.windows.com, and add AI guidance for Web Install to github.com/GoogleChrome/modern-web-guidance.

Non-OSS dependencies

Does the feature depend on any code or APIs outside the Chromium open source repository and its open-source dependencies to function?

No.

Estimated milestones

Shipping on desktop	156
Origin trial desktop first	143
Origin trial desktop last	148
Origin trial extension 1 end milestone	150
Origin trial extension 2 end milestone	150
DevTrial on desktop	139

 

Anticipated spec changes

Open questions about a feature may be a source of future web compat or interop issues. Please list open issues (e.g. links to known github issues in the project for the feature specification) whose resolution may introduce web compat/interop risk (e.g., changing to naming or structure of the API in a non-backward-compatible way).

N/A

Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/5183481574850560?gate=5120761429229568

Links to previous Intent discussions

Intent to Prototype: https://groups.google.com/a/chromium.org/d/msgid/blink-dev/DB9PR83MB05184F25E5FEE4595055FE34CC042%40DB9PR83MB0518.EURPRD83.prod.outlook.com
Ready for Trial: https://groups.google.com/a/chromium.org/g/blink-dev/c/ame_t7wN2cU
Intent to Experiment: https://groups.google.com/a/chromium.org/g/blink-dev/c/KCpVX8F6yh8/m/Fbs3p4PdAwAJ
Intent to Extend Experiment 2: https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CH3PR00MB267356EB5428C4233B819ECFD35EA%40CH3PR00MB2673.namprd00.prod.outlook.com

This intent message was generated by Chrome Platform Status.

 

[Rick Byers]

LGTM1

I read through some of the long debates on this API. From an API owner perspective, I believe all requirements have been met: spec, tests, developer feedback and needs assessment, feedback from other browser vendors. Certainly this API seems likely to be Chromium-only for the foreseeable future, but that is nothing new when it comes to advanced web app capabilities. If we can't even agree on whether WebBluetooth belongs on the web, then I don't expect us to agree on this either, but like Web Bluetooth, it's a progressive enhancement so the downside of lack of interoperability is well managed. Thank you for all the long and thoughtful engagement in public discussion and debate, I personally believe the API owners' bar is now well cleared (though other API owners may still disagree, of course). 

I personally have some concerns about the potential for annoying users and am adamant that we not repeat the push notification permission disaster, but those are Google Chrome UI concerns and are not subject to the API owners' process; they can reasonably be expected to differ across Chromium embedders. I will follow up internally on those concerns specific to Google Chrome's feature launch process. The  potential mitigation suggested in the explainer than only installed apps can install other apps would entirely adddress my concern, and I'm sure there are other (less dramatic) ways to do so as well.

Rick

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CH4PR00MB26595E5F1D84E916BDB48773D3842%40CH4PR00MB2659.namprd00.prod.outlook.com.

[Philip Jägenstedt]

LGTM2

Regarding https://wicg.github.io/install-element/#testing and testing in WPT, this should be testable with testdriver.js given a WebDriver classic endpoint or WebDriver BiDi command in the spec. https://wicg.github.io/turtledove/#sctn-automation and https://wicg.github.io/ua-client-hints/#automation are examples to copy from.

Do you have tests written outside of WPT that could be converted and upstreamed with this approach? If so, I think that would be very good to do as part of shipping.

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAFUtAY-aqgpTu7kcN%2BQaX23VNmACT0AAX00SemA6SzkaUxxiEw%40mail.gmail.com.

[Lia Hiscock]

Thanks Rick and Philip!

 

Re. the WebDriver request, I’ve opened Specify automation for Web Install confirmation-dependent WPTs · Issue #41 · WICG/install-element to track as a follow up. We do have extensive browser tests for successful installation and dismissal, but AFAIK there are no existing WebDriver endpoints or commands that fit web app installation needs.

 

From: Philip Jägenstedt <foo...@chromium.org>
Sent: Wednesday, September 30, 2026 9:04 AM
To: Rick Byers <rby...@chromium.org>
Cc: Lia Hiscock <liahi...@microsoft.com>; blin...@chromium.org; pwa...@chromium.org; Rob Paveza <Rob.P...@microsoft.com>; Limin Zhu (Edge) <li...@microsoft.com>; Kristin Lee (EDGE) <krist...@microsoft.com>; Lu Huang <Lu.H...@microsoft.com>
Subject: Re: [blink-dev] Intent to Ship: Web Install API

 

You don't often get email from foo...@chromium.org. Learn why this is important

[Dan Clark]

LGTM3