From 95fadd654b927b08ea0c4c88089f94d88fd6b561 Mon Sep 17 00:00:00 2001 From: Matt Giuca Date: Mon, 24 Apr 2017 13:59:58 +1000 Subject: [PATCH] Rework beforeinstallprompt sections. - Fixed links. - Simplified logic and fixed bugs in the algorithm. - Reworked usage example. - Rewrote some text. - Added an issue box about install prompts. - Addressed other review comments. --- index.html | 127 ++++++++++++++++++++++++++++++++--------------------- 1 file changed, 77 insertions(+), 50 deletions(-) diff --git a/index.html b/index.html index aa9e8e2d6..052ac2753 100644 --- a/index.html +++ b/index.html @@ -435,13 +435,14 @@

Queue a task on the application life-cycle task source to do the following:
    -
  1. Let target be at Window object of the - top-level browsing context. +
  2. Let event be a newly constructed + BeforeInstallPromptEvent named + beforeinstallprompt, with its cancelable + attribute initialized to true.
    3. -
  3. Let showPrompt be the result of firing an - event (event) named "beforeinstallprompt", using - BeforeInstallPromptEvent at target with its - cancelable attribute initialized to true. +
  4. Let showPrompt be the result of firing + event at the Window object of the top-level + browsing context.
  5. If showPrompt is true, then, in parallel, request to present an install prompt with @@ -450,6 +451,16 @@

+
+ Implementations may wish to show a prompt if, and only if, the site + explicitly requests it via + BeforeInstallPromptEvent.prompt(), but not + automatically without the site's approval. Is this something we want + to leave to the discretion of the user agent? (This would require + changing the language here, as "steps to notify before an automated + install prompt" would become "steps to notify that an install prompt + is available".) +

@@ -543,14 +554,22 @@

activating an automated install prompt, allowing a developer to prevent the default action for an install prompt.

-

- Thus, the default action of the BeforeInstallPromptEvent is to +

+ The default action of the BeforeInstallPromptEvent is to present an automated install prompt to the end-user. Canceling the default action (via - .preventDefault()) prevents the user agent from - presenting an automated - install prompt until a later time (see - BeforeInstallPromptEvent.prompt() method). + preventDefault) + prevents the user agent from presenting an automated install prompt. The user agent is + free to run steps to notify before an automated install prompt + 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 @@ -561,8 +580,8 @@

[[\didPrompt]]
- A boolean, initially false. Represents if this event - was used to present an install prompt to the end-user. + A boolean, initially false. Represents whether this + event was used to present an install prompt to the end-user.
[[\userResponsePromise]] @@ -581,27 +600,24 @@

steps:

    -
  1. Let p be a newly created promise. -
    2. -
  2. Resolve p with - this.[[\userResponsePromise]]. -
  3. If this.[[\userResponsePromise]] is pending:
      -
    1. If this event's isTrusted attribute is - false, reject +
    2. If this event's isTrusted + attribute is false, reject this.[[\userResponsePromise]] with NotAllowedError, optionally informing the developer that untrusted events can't call prompt().
    3. Else if this.[[\didPrompt]] is - false, then, in parallel, request to - present an install prompt with this event. Wait, possibly - indefinitely, for the end-user to make a choice. + 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.
    4. -
  4. Return p. +
  5. Return this.[[\userResponsePromise]].

@@ -613,12 +629,10 @@

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

    • @@ -628,18 +642,30 @@

    This example shows how one might prevent an automated install - prompt from showing until the user has finished a set of tasks. - Those tasks are represented as an array of promises, which the - application "awaits" to finish before an install prompt is - presented to the end-user. + prompt from showing until the user clicks a button to install the + app. 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", async (event) => {
+          
    +            window.addEventListener("beforeinstallprompt", event => {
+              // Suppress automatic prompting.
               event.preventDefault();
-              // Wait for e.g., the user to request installation from inside the app.
-              await Promise.all(tasksThatPreventsInstallation);
-              const { userChoice } = await event.prompt();
-              console.info(`user choice was: ${userChoice}`);
+
+              // 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}`);
+              });
             });
           
    
         
@@ -649,9 +675,10 @@ 
    
           Extensions to the Window object
         
    
         
    
-          The following extensions to the Window object
-          specify the event handler attributes on which events relating
-          to the installation of a web application are fired.
+          The following extensions to the Window object specify the
+          event handler attributes on which events relating to the
+          installation of a web application are fired.
         
    
         
               partial interface Window {
@@ -691,16 +718,16 @@ 
    
             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 before an automated install prompt).
+            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 before an automated install prompt).
           
    
         
    
       
    
@@ -3625,7 +3652,7 @@ 
    
         
  • 
           Fire an event
+          "fire|fired|firing">Fire an event
         
    •