From b0ad1145cdda766748befbf4c05535168b1cac22 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Tue, 9 May 2017 14:54:14 +1000 Subject: [PATCH] Feat(events): add BeforeInstallPromptEvent (#520) * Feat(events): add BeforeInstallPromptEvent (closes #417) * 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 | 186 +++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 166 insertions(+), 20 deletions(-) diff --git a/index.html b/index.html index 455efbc4c..ebb135b92 100644 --- a/index.html +++ b/index.html @@ -435,22 +435,32 @@

Queue a task on the application life-cycle task source to do the following:
    -
  1. Let event be a newly constructed - BeforeInstallPromptEvent named - "beforeinstallprompt", which is cancelable. +
  2. Let event be a newly constructed + BeforeInstallPromptEvent named + beforeinstallprompt, with its + cancelable attribute initialized to true.
    3. -
  3. - Fire event at the Window object of the - top-level browsing context. +
  4. Let showPrompt be the result of firing + event at the Window object of the top-level + browsing context.
    5. -
  5. If event's canceled flag is not set, then, - in parallel, request to present an install prompt - with event. +
  6. If showPrompt is true, then, in parallel, + request to present an install prompt with + event.
+
+ 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".) +

@@ -526,14 +536,150 @@

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

+
+

+ BeforeInstallPromptEvent Interface +

+ 
+          [Constructor]
+          interface BeforeInstallPromptEvent : Event {
+              Promise<PromptResponseObject> prompt();
+          };
+          dictionary PromptResponseObject {
+            AppBannerPromptOutcome userChoice;
+          };
+
+

+ The BeforeInstallPromptEvent is dispatched prior to + activating an automated install prompt, allowing a developer + to prevent the default action for an install prompt. +

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

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 {
@@ -573,16 +719,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).

@@ -3510,7 +3656,7 @@

  • Fire an event + "fire|fired|firing">Fire an event