diff --git a/index.html b/index.html index b24d151..a943b33 100644 --- a/index.html +++ b/index.html @@ -17,7 +17,7 @@ github: "WICG/manifest-incubations", shortName: "manifest-incubations", xref: { - specs: ["appmanifest"], + specs: ["appmanifest", "dom"], profile: "web-platform", }, }; @@ -278,5 +278,609 @@

+
+

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

+

+ 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 the user needing to interact with the user agent UI. +

+

+ 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 {{AppBannerPromptOutcome/accepted}} or + {{AppBannerPromptOutcome/dismissed}}. +
    2. +
  2. Return result, and in parallel: +
      +
    1. If result is {{AppBannerPromptOutcome/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 {{Event/cancelable}} attribute initialized to true. +
      2. +
    2. Let mayShowPrompt be the result of [=fire an + event|fire=] 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. +
+
+
+

+ Installable web applications +

+
+

+ Installation process +

+

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

+
    +
  1. Let manifest be the manifest of an installable 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. +
+
+
+

+ Installability signals +

+

+ By design, this specification does not provide developers with an + explicit API to "install" a web application. Instead, a + manifest can serve as an installability signal to a + user agent that a web application can be installed. +

+

+ Examples of installability signals for a web application: +

+
    +
  • is associated with a manifest with at least a + name member and a suitable icon. +
    • +
  • is served over a secure network connection. +
    • +
  • has a sensible content security policy. +
    • +
  • is able to responsively adapt to display on a variety of screen + sizes, catering for both mobile and desktop. +
    • +
  • is able to function without a network connection. +
    • +
  • is repeatedly used by the end-user over some extended period of + time. +
    • +
  • has been explicitly marked by the user as one that they value and + trust (e.g., by bookmarking or "starring" it). +
    • +
+

+ This list is not exhaustive and some installability signals + might not apply to all user agents. How a user agent makes use of + these installability signals to determine if a web application + can be installed is left to implementers. +

+
+
+
+

+ 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 a manual installation 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 {{Event/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 + {{BeforeInstallPromptEvent/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.{{BeforeInstallPromptEvent/[[userResponsePromise]]}} + is pending: +
      +
    1. If this event's {{Event/isTrusted}} attribute is + false, reject + this.{{BeforeInstallPromptEvent/[[userResponsePromise]]}} + with {{"NotAllowedError"}}, optionally informing the developer + that untrusted events can't call prompt(). +
      2. +
    2. Else if + this.{{BeforeInstallPromptEvent/[[didPrompt]]}} is + false, set + this.{{BeforeInstallPromptEvent/[[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.{{BeforeInstallPromptEvent/[[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.{{BeforeInstallPromptEvent/[[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). +

+
+
+
+
+

+ Associating a resource with a manifest +

+

+ A resource is said to be associated with a manifest if the + resource representation, an HTML document, has a manifest link relationship. +

+
+

+ Linking to a manifest +

+

+ The manifest keyword can be used with a [[HTML]] + [^link^] element. This keyword creates an external resource + link. +

+ + + + + + + + + + + + + + + + + + + + +
+ Link type + + Effect on... + + Brief description +
+ link + + a and area +
+ manifest + + External Resource Link + + not allowed + + Imports or links to a manifest. +
+

+ In cases where more than one [^link^] element with a + manifest link type appears in a {{Document}}, the user + agent uses the first [^link^] element in tree order and ignores all + subsequent [^link^] elements with a manifest link type + (even if the first element was erroneous). See the steps for + obtaining a manifest. +

+

+ To obtain a manifest, the user agent MUST run the steps for + obtaining a manifest. The + appropriate time to obtain the manifest is left up to + implementations. A user agent MAY opt to delay fetching a manifest + until after the document and its other resources have been fully + loaded (i.e., to not delay the availability of content and scripts + required by the document). +

+

+ A manifest is obtained and applied regardless of the + {{HTMLLinkElement/media}} attribute of the [^link^] element matches + the environment or not. +

+
+
+
+

+ Manifest life-cycle +

+

+ This section defines algorithms for obtaining, + processing, and applying a + manifest. +

+
+

+ Obtaining a manifest +

+

+ The steps + for obtaining a manifest are given by the following algorithm. + The algorithm, if successful, returns a processed manifest and + the manifest URL; otherwise, it aborts prematurely and + returns nothing. In the case of nothing being returned, the user + agent MUST ignore the manifest declaration. In running these steps, a + user agent MUST NOT delay the load event. +

+
    +
  1. From the {{Document}} of the top-level browsing context, + let origin be the {{Document}}'s origin, and manifest + link be the first [^link^] element in tree order whose + {{HTMLLinkElement/rel}} attribute contains the token + manifest. +
    2. +
  2. If origin is an opaque origin, then abort these + steps. +
    3. +
  3. If manifest link is null, then abort + these steps. +
    4. +
  4. If manifest link's href attribute's value + is the empty string, then abort these steps. +
    5. +
  5. Let manifest URL be the result of [=URL + Parser|parsing=] the value of the href attribute, + relative to the element's base URL. If parsing fails, then + abort these steps. +
    6. +
  6. Let |request:Request| be a new Request. +
    7. +
  7. Set |request|'s [=request/URL=] to |manifest URL|. +
    8. +
  8. Set |request|'s [=request/initiator=] to "`manifest`". +
    9. +
  9. Set |request|'s [=request/destination=] to "`manifest`". +
    10. +
  10. If the |manifest link|'s {{HTMLLinkElement/crossOrigin}} + attribute's value is "`use-credentials`", then set |request|'s + [=request/credentials mode=] to "`include`". Otherwise, set + |request|'s [=request/credentials mode=] to "`omit`". +
    11. +
  11. Set |request|'s [=request/mode=] to "`cors`". +
    12. +
  12. Await the result of performing a fetch with + request, letting response be the result. +
    13. +
  13. If response is a network error, then abort + these steps. +
    14. +
  14. Let text be UTF-8 decode response's + body. +
    15. +
  15. Let manifest be the result of running processing a + manifest given text, manifest URL, and the + URL that represents the address of the top-level browsing + context. +
    16. +
  16. Return manifest and manifest URL. +
    17. +
+
+

+ Content security policy +

+

+ A user agent MUST support [[CSP3]]. +

+
+

+ The manifest-src and default-src directives govern + the origins from which a user agent can fetch a manifest. + As with other directives, by default the manifest-src + directive is *, meaning that a user agent can, + [[FETCH]]'s CORS permitting, fetch the manifest + cross-domain. Remote origins (e.g., a CDN) wanting to host manifests + for various web applications will need to include the appropriate + CORS response header in their HTTP response (e.g., + Access-Control-Allow-Origin: https://example.com). +

+
+ manifest-src directive example illustrated +
+ For a [[HTML]] document, [[CSP3]]'s manifest-src + directive controls the sources from which a [[HTML]] document + can load a manifest from. The same CSP policy's + img-src directive controls where the icon's images + can be fetched from. +
+
+
+
+
+