From a96f936ed57202cb5e0a3c49786fd5a3730ca538 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Fri, 13 Dec 2019 17:40:43 +1100 Subject: [PATCH 01/10] BREAKING CHANGE: remove beforeinstallprompt event --- index.html | 321 +++-------------------------------------------------- 1 file changed, 13 insertions(+), 308 deletions(-) diff --git a/index.html b/index.html index 60726c1de..a5cb04751 100644 --- a/index.html +++ b/index.html @@ -397,121 +397,20 @@

-
- -

- Install prompts -

-

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

-
    -
  • An end-user can manually - trigger the installation process through the user agent's - UI, directly invoking the steps - to present an install prompt. -
    • -
  • The installation process can occur through an automated - install prompt: that is, a UI that the user agent presents to - the user when, for instance, there are sufficient installability - signals to warrant installation of the web application. -
    • -
  • The installation process can occur through a site-triggered - install prompt: the site can programmatically request that the - user agent present an install prompt to the user. The user agent MAY - restrict the availability of this feature to cases where, for - instance, there are sufficient installability signals to - warrant installation of the web application. -
    • -
-

- 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 allow 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 @@ -583,204 +482,22 @@

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 + 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. + 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;
           };
         
             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). -

-
From caec619c0ef8e49514731742fbcc2158cec81840 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Mon, 30 Mar 2020 14:14:34 +1100 Subject: [PATCH 02/10] Remove window.oninstalled event --- index.html | 90 ++++-------------------------------------------------- 1 file changed, 6 insertions(+), 84 deletions(-) diff --git a/index.html b/index.html index 7eed2ece6..d4d54f456 100644 --- a/index.html +++ b/index.html @@ -315,9 +315,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 @@ -325,9 +325,9 @@

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

    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. -
    -

    Privacy and security considerations @@ -472,8 +444,8 @@

    Uninstallation

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

    It is RECOMMENDED that at the time of removal, the user agent also @@ -483,56 +455,6 @@

    -
    -

    - Installation Events -

    -

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

    -
    -

    - 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;
-          };
-
    - 
    -          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). -

    -
    -
    -

    Navigation scope From b386d34a79d98e0984485186f0bded6fb8d6f974 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Mon, 30 Mar 2020 15:32:07 +1100 Subject: [PATCH 03/10] Add incubations section --- index.html | 31 +++++++++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index d4d54f456..f7a9162f6 100644 --- a/index.html +++ b/index.html @@ -327,8 +327,8 @@

    -
  • Otherwise, the {{Document}} is considered installable - (at the user agent's discretion; see [[[#installability-signals]]]). +
  • Otherwise, the {{Document}} is considered installable (at + the user agent's discretion; see [[[#installability-signals]]]).
    • @@ -3226,6 +3226,33 @@

    +
    +

    + Incubations +

    +

    + Non-standard extensions to this specification are being "incubated" in + parallel by the Web Community. If two or more implementers decide to + support an incubated feature, then those features will become part of + this specification in the future: +

    +
    +
    + `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 didn't not have support from two or + more implementers. You can now find them in the `BeforeInstallPrompt` + event and `window.onappinstalled` repository at the WICG. +
    +
    +

    Relationship to HTML's link and meta elements From 2b863c9ff0e3c2241379715d64baa7579feed276 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Mon, 30 Mar 2020 17:04:53 +1100 Subject: [PATCH 04/10] Add share_target to incubations --- index.html | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/index.html b/index.html index 25cd24553..d0a3d2300 100644 --- a/index.html +++ b/index.html @@ -3253,6 +3253,17 @@

    "https://wicg.io">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. +

    From 05e7952a24f5a2ce82eec2c5eb140c05305ae9b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Tue, 31 Mar 2020 11:23:08 +1100 Subject: [PATCH 05/10] Remove DOM deps --- index.html | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/index.html b/index.html index d0a3d2300..86d35e291 100644 --- a/index.html +++ b/index.html @@ -3506,18 +3506,6 @@

    -
  • [[DOM]] defines the following terms: - -
  • [[HTML]] defines the following terms:
  • [[INFRA]] defines the following terms: From f3053d12695bf0301fee986d7998b6c1e18729c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Tue, 31 Mar 2020 11:51:33 +1100 Subject: [PATCH 09/10] Remove dep on completely loaded from HTML --- index.html | 4 ---- 1 file changed, 4 deletions(-) diff --git a/index.html b/index.html index cfc5201e1..6d12b727a 100644 --- a/index.html +++ b/index.html @@ -3509,10 +3509,6 @@

  • [[HTML]] defines the following terms:
    • -
  • Otherwise, the {{Document}} is 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]]]).
    • @@ -382,7 +382,7 @@

    It is RECOMMENDED that UI that affords the end user the ability to - install a web application also allow inspecting the icon, + 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 @@ -3465,18 +3465,6 @@

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