From 7a9d04d8e1259c4a3f9229c7d5adef12b39bba71 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 --- index.html | 165 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) diff --git a/index.html b/index.html index f9353b0ee..a5c93bd9d 100644 --- a/index.html +++ b/index.html @@ -447,6 +447,171 @@

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

+
+

+ BeforeInstallPromptEvent Interface +

+ 
+          [Constructor(DOMString typeArg, optional BeforeInstallPromptEventInit eventInit)]
+          interface BeforeInstallPromptEvent : Event {
+              readonly attribute Promise<AppBannerPromptOutcome> userChoice;
+              Promise<UserResponseObject> prompt();
+          };
+
+          dictionary BeforeInstallPromptEventInit : EventInit {
+            AppBannerPromptOutcome userChoice;
+          };
+
+          dictionary UserResponseObject {
+            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). +

+

+ The BeforeInstallPromptEvent has three internal slots, which + are set when the event is constructed: +

+
+
+ [[\didPrompt]] +
+
+ A boolean, initially false. Represents if this event + was used to present an install prompt to the end-user. +
+
+ [[\promptOutcome]] +
+
+ A AppBannerPromptOutcome enum value, initially set to + null. Represents the outcome of presenting an + install prompt. +
+
+ [[\userResponsePromise]] +
+
+ A promise, which resolves with an UserResponseObject, which + represent the outcome of presenting an install prompt. +
+
+
+

+ Constructor +

+

+ To construct an instance of the BeforeInstallPromptEvent + interface, run the steps to construct a + BeforeInstallPromptEvent event: +

+
    +
  1. Let [[\didPrompt]] be false. +
    2. +
  2. Let [[\userResponsePromise]] be a newly created promise. +
    3. +
  3. Let [[\promptOutcome]] be null. +
    4. +
  4. If eventInit.userChoice is valid, then: +
      +
    1. Resolve [[\userResponsePromise]] with + eventInit.userChoice. +
      2. +
    2. Set [[\promptOutcome]] to the value of + eventInit.userChoice. +
      3. +
    +
    5. +
+
+
+

+ prompt() method +

+

+ The prompt method, when called, runs the following + steps: +

+
    +
  1. Let p be a newly created promise. +
    2. +
  2. Run the following steps in parallel: +
      +
    1. If [[\promptOutcome]] is not null, + resolve p with [[\userResponsePromise]] and + terminate this algorithm. +
      2. +
    2. If this event's isTrusted attribute is + false, reject [[\userResponsePromise]] with + NotAllowedError, optionally informing the developer + that untrusted events can't call prompt(). +
      3. +
    3. Else if [[\didPrompt]] is false, then + request to present an install prompt and wait, possibly + indefinitely, for the end-user to make a choice. +
      4. +
    4. Upon fulfillment of [[\userResponsePromise]], resolve + p with [[\userResponsePromise]]. +
      5. +
    +
    3. +
  3. Return p. +
    4. +
+

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

+
    +
  1. + Present an install prompt and let event's + [[\promptOutcome]] be the result. +
    2. +
  2. Let userResponseObj be a newly created + UserResponseObject whose userChoice member is + set to event's [[\promptOutcome]]. +
    3. +
  3. Resolve [[\userResponsePromise]] with + userResponseObject. +
    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 function(event) {
+              event.preventDefault();
+              // await e.g., user composing an email...
+              await Promise.all(tasksThatPreventsInstallation);
+              const { userChoice } = await event.prompt();
+              console.info(`user selected: ${userChoice}`);
+            });
+
+
+

Extensions to the Window object