Intent to Ship: HTML install element

[Lia Hiscock]

Contact emails

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

Explainer

https://aka.ms/installelement

Specification

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

Design docs
https://docs.google.com/document/d/1rGvLhD4SR8Y9M1wVmqgyesPNkbZGU7HOqlttjEFJ5Vo/edit?tab=t.tmx19oox759l#heading=h.j3tt49hqiuck

Summary

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

 

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

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/installelement

Search tags

webinstall, webappinstallation, webinstallapi, installelement

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

HTML Install Element

Chromium Trial Name

InstallElement

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-element/README.md at main · MicrosoftEdge/Demos

WebFeature UseCounter name

WebDXFeature::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 rendering the install element. There is overlap between this install element and the BeforeInstallPrompt event. This element is more ergonomic, and we think developers will prefer its declarative format. 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 element was designed with ergonomics in mind, and we have multiple places with instructions for developers (two test sites, and the explainer itself)

Security

The element proposal came out of security concerns with imperative APIs, specifically that an API to trigger the PWA installation flow cannot provide a strong enough signal of user intent to install an app, thereby increasing the risk of abuse and annoyance to users.

 

<install> inherits from a base capability element, which has many security protections, such as (1) restrictions on element styling/sizing (eg. it cannot be fully transparent, and it has a minimum and maximum size), (2) preventing activation if out of view, or recently attached to the tree, and (3) preventing clipping/occlusion/distortion.

 

See explainer's security section - https://github.com/WICG/install-element/blob/main/explainer-manifest-url.md#accessibility-localization-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 HTML elements applies. The base capability element also reports customized DevTools Issues when the browser cannot safely allow activation. In addition, 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. 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 element's base styling/activation restrictions are tested - https://wpt.fyi/results/html/semantics/permission-element/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://github.com/MicrosoftEdge/Demos/blob/main/pwa-install-element/README.md

Flag name on about://flags

web-app-install-element

Finch feature name

InstallElement

Rollout plan

Will ship enabled for all users

Requires code in //chrome?

False

Tracking bug

https://issues.chromium.org/issues/454827186

Launch bug

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

Measurement

We have a JavaScript use counter that tracks how often the element is found in pages (regardless of whether it can be activated). We also have chromium UMAs and UKMs.

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	148
Origin trial desktop last	153

 

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/5152834368700416?gate=6500019899334656

Links to previous Intent discussions

Intent to Experiment: https://groups.google.com/a/chromium.org/g/blink-dev/c/N1AjeFmVF4U/m/YrAdZgaIAAAJ

This intent message was generated by Chrome Platform Status.

 

[Rick Byers]

LGTM1

As for the install API, I believe all API owner requirements have been met.

This is exactly the sort of scenario capability elements were designed for: they give us a mechanism that is both user-initiated and browser-UI-controlled while also enabling site developers to PLACE and TIME the UI appropriately for their application.  From all the evidence and public debate I have seen (including Safari's rich support for promoting native app install), I believe WebKit's opposition to this has more to do with what's best for Apple's business model than what's in the best interest of users and developers of the web. 

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/CH4PR00MB2659F34720E44CB1DB438CD6D3842%40CH4PR00MB2659.namprd00.prod.outlook.com.

[Philip Jägenstedt]

LGTM2

Can you please file an issue on https://github.com/whatwg/html/issues about integrating this into the HTML spec if implementer interest from Gecko or WebKit materializes?

I looked over the spec with a "what if this were a HTML PR" lens and filed these two issues:

https://github.com/WICG/install-element/issues/36

https://github.com/WICG/install-element/issues/37

At least the first is about the API shape, so if you agree can please you make that change to spec and impl before shipping? (For the second I'm not sure if null is ever returned by the implementation, and if not it's just a matter of clearer Web IDL types.)

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAFUtAY_tJGHbDgu3hS8%3Drt5WWsJP8WwBr6TmeK4kDfC1zvDW8g%40mail.gmail.com.

[Philip Jägenstedt]

I took another look and it looks like the reflected attributes can return null:

https://github.com/web-platform-tests/wpt/blob/1b81534c42533f63bf293db633598f9ff9ab6aba/html/semantics/permission-element/install/install-element-url-attributes.tentative.html#L10-L15

That never happens for other HTML elements with reflected URL attributes AFAICT, so I think this is also important to change as it's part of the API surface.

[Dan Clark]

Looking through https://wicg.github.io/install-element I see 36 Issues noted in the spec. Do any of these need to be followed up on before this should ship? At least some look like potential enhancements, which we needn't block for. But are there any that could lead to compat-affecting changes for what'd be shipping with this Intent or the Web Install API Intent?

-- Dan

[Lia Hiscock]

Hi Dan! Thanks for the feedback. We've completed our review of the open spec issues and completed the following PRs. [1] contains the bulk of the issues.

[1] https://github.com/WICG/install-element/pull/42 (Merged)

[2] https://github.com/WICG/install-element/pull/40 (Merged)

We identified a handful of issues as needing pre-ship code changes -- those are listed in the description of [1]. Six of the CLs have merged in Chromium, and three more are in progress.

We are planning to open one last spec PR for the tail end of the issues, which I'll make sure to merge before anything ships.

Thanks!

Lia

[Dan Clark]

Thank you for working through these! LGTM3