Repository files navigation

Web applications can be installed, providing users with a more reliable and integrated experiencealongside other applications they may use on a regular basis. This is generally considered to befantastic, providing value to both users and developers.

Today, the process of initiating an installation flow is somewhat fragmented; each user agent hascreated a set of entry points, some more discoverable and intuitive than others. TheWeb Install API, currently in Origin Trials, aims to create a more consistent developer-facing story, providing an imperative API which allows websites to initiate an installation flow for an arbitrary application,enabling more seamless and intuitive experiences for users.

However, an imperative API does not provide a strong signal of a user's intent to perform the action, as the only restriction is transient activation. This opens the door for potential abuse or annoyance. Seerisks of the imperative API.

We can provide developers with a declarative<install> element which renders a button whose content and presentation is controlled by the user agent. Similar to otherpermission elements (e.g.<geolocation>), the user agent's control over (and thereforeunderstanding of) the element's content means that it can make plausible assumptions about a user's contextual intent. Users who click on a button labeled "Install 'Wonderful Application'" are unlikely to be surprised if an installation prompt for exactly that application appears, and they'll be primed to make a good decision about the question such a prompt presents.

The element will render standardized text and iconography controlled by the user agent, such as:

<installinstallurl="https://music.youtube.com/"manifestid="https://music.youtube.com/?source=pwa">  [Fallback content goes here.]</install>

installurl specifies the document to install (this is equivalent to the first parameter of the imperative version). This enables loading the document in the background and obtaining the information needed for the installation dialog. If unspecified, the current document will be installed.

manifestid is optional. Ifunspecified, the manifest referenced by the document atinstallurl must have a custom id defined. If specified, it must match the computed id of the site to be installed.

On click, the user agent can display a confirmation prompt with the app's name, origin, and icon for increased security.

The initial design is deliberately simple, as the primary goal is to gather usage data -- How useful do web developers find a declarative installation method, given certain style restrictions?

At the same time, we also believe the simple button is a sufficient signal of user intent. The original premise of PEPC is that a standardized label and icon signal a user's intent to perform a permission-related action. In this case, the user indicates their intent to install content by clicking on the element, and then the user agent can present more detailed information for evaluation and final confirmation.

We see value in including app-specific text and iconography, and potentially skipping the secondary confirmation UI entirely, but this introduces a variety of concerns. To avoid scope creep, this has been moved toFuture Work, where it can be addressed while we're gathering feedback on the element's overall shape.

It's worth noting that the button's exact rendering may eventually be useful ambiguity from a standards perspective. It would allow each user agent to decide what information they need, and how to address the above concerns.

If the user agent doesn't support installation, present a simple link:

<installinstallurl="https://music.youtube.com/"manifestid="https://music.youtube.com/?source=pwa"><ahref="https://music.youtube.com/"target="_blank">      Launch YouTube Music</a></install>

The element can transform into a simple 'Launch'-style button, a highly requested feature from web developers. However, we must ensure developers cannot detect the change in the element's content to avoid fingerprinting concerns. This means being careful about side channels, particularly width.

The element offers event-driven hooks allowing developers to understand users' interactions, reusingInPagePermissionMixin concepts likepromptaction,promptdismiss, andvalidationstatuschange events,isValid andinvalidReason attributes, etc. Additional events will be needed for failures related to manifest fetching/parsing.

Validation errors could include violations of the generally applicablepresentation restrictions for permission elements, as well as data validation errors when processing the referenced manifest.

That said, developers wouldn't actually need to hook into any of those attributes for the simplestcases:<install installurl="https://example.com/"></install> would be sufficient forstraightforward use cases of offering installation.

Ok. Here you go:

[Exposed=Window]interface HTMLInstallElement : HTMLElement {  [HTMLConstructor] constructor();  [CEReactions, ReflectURL] attribute USVString installurl;  [CEReactions] attribute USVString manifestid;};HTMLInstallElement implements InPagePermissionMixin;

TheInPagePermissionMixin is defined as part of the general PermissionElement proposal, and includes a few attributes and events. We'll reuse those herefor consistency.

• isValid will return a boolean:true if the element's presentation makes it a valid clicktarget for users (because the user agent has confidence that it's visible and comprehensible,and that it's been in that state long enough to be reasonably reliably viewed and comprehended),false otherwise.

• invalidReason will return an enum specifying the reason the element is considered invalid,including invalidity of the element's underlying data (for cases in which the URL is missingor invalid, or manifest fetching/parsing fails).

• initialPermissionStatus andpermissionStatus will reflect the state of theinstall feature(which we'll define somewhere as a policy-controlled feature with a default allowlist of'self').

• promptaction events will be fired when the user finishes interacting with any installationprompt triggered by activating the element.

• Likewise,promptdismiss will be fired when users cancel or dismiss the installation prompt.

• validationstatuschange events fire when the validation status changes (crazy, right?).

The element'sactivation behavior is quite similar to other permissionelements (e.g.<geolocation>'s activation behavior): we'll check to see whetherthe event is trustworthy, the element is valid, permission toinstall is available and so on.Then we'll trigger an installation prompt in an implementation defined way. This will result inthe user making some decision, leading to either apromptdismiss orpromptaction event firingon the element.

The element hooks directly into the backend of navigator.install. When clicked, it willload theinstallurl in the background to obtain the web application manifest and relatedresources needed for the installation dialog. The steps here will be similar to those definedforthe "manifest" link type, fetching and processing the manifest accordingto itsprocessing steps. If we get a valid manifest back, the installationdialog is presented. If not, an error event is fired and the<install> element reports theerror appropriately.

The following features are planned for future iterations:

Rendering the app name, origin, or icon in the install element would provide an even stronger signal of user intent, but also introduces a variety of complications, such as:

• Performance: When and how to get the information to show in the button
• UX: Whether to use a two-tap flow (tap 1 loads info, tap 2 installs)
• Security: Long app names. Seehandling very long app names. Is the secondary installation confirmation prompt necessary?
• Styling/Accessibility: App icon contrast ratios. Button layout/width.

We believe it's worth it to solve these problems, but don't think it should delay gathering initial feedback.

• manifesturl: Link to the manifest file
• includeicon: If specified, fetches and renders the app's icon (in addition to the install icon)

• We don't generally consider the act of installation to be a security boundary today, though thereare capabilities that we only offer to installed applications (often around integration with thenative OS, ranging fromfile_handlers to homescreen icons), and some forms of friction thatsome user agents reduce when applications are installed (notifications, badging, etc). It seemslikely to me that an imperative version of this capability will create some of the same incentivesfor abuse that we've seen with notifications, which suggests that raising the bar for triggeringan installation prompt might be reasonable. This proposal does so in a way that seems to provideadditional confidence that the user actually wants to install something, and does so in a way thatseems relatively lightweight.

• Cross-origin installation requires us to talk about one origin in the context of another. This issomewhat difficult to do effectively.

• The user-facing benefits claimed above depend entirely on the truth of the claim that users do seeand understand the element's representation. This means both that user agents need to doappropriate research to ensure the pixels they present in the element are in fact reasonablycomprehensible,and evaluate their installation flows to ensure that they set user expectationscorrectly.

• Sites which wish to ensure that users can only install their applications from their own origincan do so by examining Fetch Metadata headers in the incoming request for a given manifest andhandle things appropriately in the case thatSec-Fetch-Dest ismanifest, butSec-Fetch-Siteis notsame-origin.

Security and privacy concerns were raised thatnavigator.install makes it easier to push installation prompts out to users, and risks creating new opportunities for annoyance or abuse. The imperative proposal recognizes this risk,suggestingtransient activation and explicit delegation as requirements. These arepotentially helpful, but don't actually do much to ensure that users are neither surprised,confused, nor annoyed by prompts when they appear. Top-level navigation is not a substantialbarrier, and clicks of any sort can be intercepted for the API's purpose, regardless of what theuser thinks they're clicking on.

While it's certainly possible to layer other heuristics on top of the transient activationrequirement to mitigate abuse (rate limits, crowd-sourced judgements, etc), it seems advisable toavoid the risk in the first place by shifting to a model that requires a stronger signal of userintent.

User agents will need to consider how to handle very long words, including appropriate resizing, eliding, and truncation logic (similar to what the installation dialog already implements). User agents should apply the same considerations they useelsewhere for displaying origins and names.

• Given that the behavior discussed above would support both installation and launching, dependingon the application's installed state, some more generic name might be appropriate.<pwa> or<webapp> could more broadly describe a potential range of behavior. I prefer<install>, aslaunching seems like it's really just a privacy-preserving mechanism to align behavior withoutrevealing installation state, but another broader name could certainly be preferable.