diff --git a/index.html b/index.html index a75d9831d..a9294c1a3 100644 --- a/index.html +++ b/index.html @@ -317,9 +317,9 @@

  • If obtaining the manifest results in an error, the user agent MAY either: -
      +
      • Fall back to using the top-level browsing context - {{Document}}'s metadata to to populate manifest in a + {{Document}}'s metadata to populate manifest in a user-agent-specific way (e.g., setting |manifest|.{{WebAppManifest/name}} to the document `title`) and considering the document @@ -327,10 +327,10 @@

      • Or, consider the document not installable.
        • -
    +
    • -
  • Otherwise, the {{Document}} MAY be considered installable - (at the user agent's discretion; see [[[#installability-signals]]]). +
  • Otherwise, at its discretion, the user agent MAY consider the + {{Document}} installable (see [[[#installability-signals]]]).
    • @@ -376,149 +376,20 @@

    might be better suited for the space available underneath an icon).

    -
    -

    - Installation process -

    -

    - The steps to install the web application are given by the - following algorithm: -

    -
      -
    1. Let manifest be the manifest value created during - steps to determine installability of the document. -
      2. -
    2. Perform an unspecified sequence of actions to attempt to register - the web application in the user's operating system (e.g., create - shortcuts that launch the web application, register the application - in the system uninstall menu, etc.). If the installation fails (which - can be for any reason, for example, the OS denying permission to the - user agent to add an icon to the home screen of the device), abort - these steps. -
      3. -
    3. - Queue a task on the application life-cycle task - source to fire an event named appinstalled - at the the {{Window}} object of the top-level browsing - context for which the installation took place. -
      4. -
    -
    -
    - -

    - Install prompts -

    -

    - There are multiple ways that the installation process can be - triggered: -

    - -

    - In any case, the user agent MUST NOT present an install prompt - if the document is not installable. -

    -

    - Prior to presenting an automated install prompt, a user agent - MUST run the steps to notify that an install prompt is - available, to give the site the opportunity to prevent the - default action (which is to install the application). Alternatively, - the user agent MAY, at any time (only if the document is - installable), run the steps to notify that an install - prompt is available at any time, giving the site the opportunity - to show a site-triggered install prompt without automatically - showing the prompt. -

    -

    - To present - an install prompt: -

    -
      -
    1. Show some user-agent-specific UI, asking the user whether to - proceed with installing the app. See privacy and security considerations for - recommendations relating to this UI. The result of this - choice is either accepted or dismissed. -
      2. -
    2. Return result, and in parallel: -
        -
      1. If result is accepted, run the steps to - install the web application. -
        2. -
      -
      3. -
    -

    - The steps to notify that an install prompt is available - are given by the following algorithm: -

    -
      -
    1. Wait until the {{Document}} of the top-level browsing - context is completely loaded. -
      2. -
    2. If there is already an install prompt being presented or if - the steps to install the web application are currently being - executed, then abort this step. -
      3. -
    3. - Queue a task on the application life-cycle task - source to do the following: -
        -
      1. Let event be a newly constructed - BeforeInstallPromptEvent named - beforeinstallprompt, with its - cancelable attribute initialized to true. -
        2. -
      2. Let mayShowPrompt be the result of firing - event at the {{Window}} object of the top-level - browsing context. -
        3. -
      3. If mayShowPrompt is true, then the user agent MAY, - in parallel, request to present an install prompt - with event. -
        4. -
      -
      4. -
    -

    Privacy and security considerations

    - During the presentation of the install prompt, it is - RECOMMENDED that the user agent allow the end-user to inspect the - icon, name, start URL, origin, etc. pertaining to a web - application. This is to give an end-user an opportunity to make a - conscious decision to approve, and possibly modify, the information - pertaining to the web application before installing it. This also - gives the end-user an opportunity to discern if the web application - is spoofing another web application, by, for example, using an - unexpected icon or name. + It is RECOMMENDED that UI that affords the end user the ability to + install a web application also allows inspecting the icon, + name, start URL, origin, etc. pertaining to a web application. + This is to give an end-user an opportunity to make a conscious + decision to approve, and possibly modify, the information pertaining + to the web application before installing it. This also gives the + end-user an opportunity to discern if the web application is spoofing + another web application, by, for example, using an unexpected icon or + name.

    It is RECOMMENDED that user agents prevent other applications from @@ -575,7 +446,7 @@

    Uninstallation

    - User agents SHOULD provide a mechanism for the user to remove the + User agents SHOULD provide a mechanism for the user to remove an installed web application application.

    @@ -586,250 +457,6 @@

    -
    -

    - Installation Events -

    -

    - Installation events and supporting the {{BeforeInstallPrompt}} is - OPTIONAL. -

    -

    - DOM events fired by this specification use the application - life-cycle task source. -

    -
    -

    - BeforeInstallPromptEvent Interface -

    -
    - The beforeinstallprompt event is somewhat misnamed, as it does - not necessarily signal that an automated install prompt will - follow (depending on the user agent, it might just be giving the site - the ability to trigger an install prompt). It is so named for - historical reasons. -
    - 
    -          [Exposed=Window]
-          interface BeforeInstallPromptEvent : Event {
-            constructor(DOMString type, optional EventInit eventInitDict = {});
-            Promise<PromptResponseObject> prompt();
-          };
-
-          dictionary PromptResponseObject {
-            AppBannerPromptOutcome userChoice;
-          };
-
-          enum AppBannerPromptOutcome {
-            "accepted",
-            "dismissed"
-          };
-
    -

    - The BeforeInstallPromptEvent is dispatched when the site is - allowed to present a site-triggered install prompt, or prior - to the user agent presenting an automated install prompt. It - allows the site to cancel the automated install prompt, as - well as manually present the site-triggered install prompt. -

    -
    - If the BeforeInstallPromptEvent is not cancelled, the - user agent is allowed to present an install prompt - (specifically, an automated install prompt) to the end-user. - Canceling the default action (via preventDefault) prevents the user - agent from presenting an install prompt. The user agent is - free to run steps to notify that an install prompt is - available again at a later time. -
    -

    - The PromptResponseObject contains the result of calling - prompt(). It - contains one member, userChoice, which states the user's - chosen outcome. -

    -

    - An instance of a BeforeInstallPromptEvent has the following - internal slots: -

    -
    -
    - [[\didPrompt]] -
    -
    - A boolean, initially false. Represents whether this - event was used to present an install prompt to the end-user. -
    -
    - [[\userResponsePromise]] -
    -
    - A promise that represents the outcome of presenting an install - prompt. -
    -
    -
    -

    - prompt() method -

    -

    - The prompt method, when called, runs the following - steps: -

    -
      -
    1. If this.[[\userResponsePromise]] is pending: -
        -
      1. If this event's isTrusted attribute - is false, reject - this.[[\userResponsePromise]] with - {{"NotAllowedError"}}, optionally informing the developer that - untrusted events can't call prompt(). -
        2. -
      2. Else if this.[[\didPrompt]] is - false, set this.[[\didPrompt]] - to true, then in parallel, request to - present an install prompt with this event. Wait, possibly - indefinitely, for the end-user to make a choice. -
        3. -
      -
      2. -
    2. Return this.[[\userResponsePromise]]. -
      3. -
    -

    - To request to present an install prompt - with BeforeInstallPromptEvent event: -

    -
      -
    1. - Present an install prompt and let outcome be - the result. -
      2. -
    2. Resolve event.[[\userResponsePromise]] with a - newly created PromptResponseObject whose userChoice member is the value of - outcome. -
      3. -
    -
    -
    -

    - Usage example -

    -

    - This example shows how one might prevent an automated install - prompt from showing until the user clicks a button to show a - site-triggered install prompt. In this way, the site can - leave installation at the user's discretion (rather than prompting - at an arbitrary time), whilst still providing a prominent UI to do - so. -

    - 
    -            window.addEventListener("beforeinstallprompt", event => {
-              // Suppress automatic prompting.
-              event.preventDefault();
-
-              // Show the (disabled-by-default) install button. This button
-              // resolves the installButtonClicked promise when clicked.
-              installButton.disabled = false;
-
-              // Wait for the user to click the button.
-              installButton.addEventListener("click", async e => {
-                // The prompt() method can only be used once.
-                installButton.disabled = true;
-
-                // Show the prompt.
-                const { userChoice } = await event.prompt();
-                console.info(`user choice was: ${userChoice}`);
-              });
-            });
-
    -
    -
    -

    - AppBannerPromptOutcome enum -

    -

    - The AppBannerPromptOutcome enum's values represent the - outcomes from presenting an install prompt. -

    -
    -
    - accepted: -
    -
    - The end-user indicated that they would like the user agent to - install the web application. -
    -
    - dismissed: -
    -
    - The end-user dismissed the install prompt. -
    -
    -
    -
    -
    -

    - Extensions to the Window object -

    -

    - The following extensions to the Window object specify - the event handler idl attribute on which events relating to - the installation of a web application are fired. -

    - 
    -          partial interface Window {
-            attribute EventHandler onappinstalled;
-            attribute EventHandler onbeforeinstallprompt;
-          };
-
    - 
    -          function handleInstalled(ev) {
-            const date = new Date(ev.timeStamp / 1000);
-            console.log(`Yay! Our app got installed at ${date.toTimeString()}.`);
-          }
-
-          // Using the event handler IDL attribute
-          window.onappinstalled = handleInstalled;
-
-          // Using .addEventListener()
-          window.addEventListener("appinstalled", handleInstalled);
-
    -
    -

    - onappinstalled attribute -

    -

    - The onappinstalled is an event handler IDL - attribute for the "appinstalled" event type. The - interface used for these events is the Event - interface [[DOM]]. This event is dispatched as a result of a - successful installation (see the steps to install the web - application). -

    -
    -
    -

    - onbeforeinstallprompt attribute -

    -

    - The onbeforeinstallprompt is an event handler IDL - attribute for the "beforeinstallprompt" event type. - The interface used for these events is the - BeforeInstallPromptEvent interface (see the steps to - notify that an install prompt is available). -

    -
    -
    -

    Navigation scope @@ -3610,6 +3237,45 @@

    +
    +

    + Incubations +

    +

    + Extensions to this specification are being incubated in parallel by the + Web Community, some of which are shipping in multiple browsers. If two + or more browser engines end up supporting an incubated feature, then + those features will become part of this specification in the future - + allowing them to become a standard the Web Platform: +

    +
    +
    + `BeforeInstallPrompt` and `window.onappinstalled` event +
    +
    + The `BeforeInstallPrompt` event and `window.onappinstalled` event + were originally part of this specification. However, they were + removed from the + specification because they did not have support from two or more + implementers. You can now find them in the `BeforeInstallPrompt` + event and `window.onappinstalled` repository at the WICG. +
    +
    + `share_target` member +
    +
    + The `share_target` member registers a web application as "target" for + share actions (e.g., for sharing a text, a URL, or a file). The + `share_target` member is part of the Web Share Target + specification, being incubated at the WICG. +
    +
    +

    Relationship to HTML's link and meta elements @@ -3799,24 +3465,8 @@

    -
  • [[DOM]] defines the following terms: - -
  • [[HTML]] defines the following terms:
  • [[ECMASCRIPT]] defines the following terms: