From 3ee567bb1fddf7ee5b2f2039735773804a8f2d8f Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Mon, 7 Nov 2016 20:39:39 +1100 Subject: [PATCH] Feat(events): add BeforeInstallPromptEvent (closes #417) --- index.html | 140 ++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 129 insertions(+), 11 deletions(-) diff --git a/index.html b/index.html index fc2c1d1ae..193f89fe4 100644 --- a/index.html +++ b/index.html @@ -399,18 +399,17 @@

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 target be at Window object of the + top-level browsing context.
    3. -
  3. - Fire event at the Window object of the - top-level browsing context. +
  4. Let showPrompt be the result of firing an + event (event) named "beforeinstallprompt", using + BeforeInstallPromptEvent at target with its + cancelable attribute initialized to true.
    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.
@@ -490,6 +489,125 @@

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

+

+ Thus, 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). +

+

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

+
+
+ [[\didPrompt]] +
+
+ A boolean, initially false. Represents if 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. Let p be a newly created promise. +
    2. +
  2. Resolve p with + this.[[\userResponsePromise]]. +
    3. +
  3. 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, then, in parallel, request to + present an install prompt with this event. Wait, possibly + indefinitely, for the end-user to make a choice. +
      3. +
    +
    4. +
  4. Return p. +
    5. +
+

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

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

+ Usage example +

+

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

+ 
+            window.addEventListener("beforeinstallprompt", async (event) => {
+              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}`);
+            });
+
+
+

Extensions to the Window object @@ -3028,7 +3146,7 @@

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