Skip to content

Commit 0a05f3e

Browse files
marcoscaceresmgiuca
marcoscaceres
authored and
mgiuca
committed
Feat(events): add BeforeInstallPromptEvent (closes #417)
1 parent a34e938 commit 0a05f3e

File tree

1 file changed

+129
-11
lines changed

1 file changed

+129
-11
lines changed

‎index.html

Lines changed: 129 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -435,18 +435,17 @@ <h2>
435435
<a>Queue a task</a> on the <a>application life-cycle task
436436
source</a> to do the following:
437437
<ol>
438-
<li>Let <var>event</var> be a <a data-lt=
439-
"construct a BeforeInstallPromptEvent">newly constructed</a> <a>
440-
BeforeInstallPromptEvent</a> named
441-
"<a>beforeinstallprompt</a>", which is cancelable.
438+
<li>Let <var>target</var> be at <a>Window</a> object of the
439+
<a>top-level browsing context</a>.
442440
</li>
443-
<li>
444-
<a>Fire</a> <var>event</var> at the <a>Window</a> object of the
445-
<a>top-level browsing context</a>.
441+
<li>Let <var>showPrompt</var> be the result of <a>firing an
442+
event</a> (<var>event</var>) named "beforeinstallprompt", using
443+
<a>BeforeInstallPromptEvent</a> at <var>target</var> with its
444+
<code>cancelable</code> attribute initialized to true.
446445
</li>
447-
<li>If <var>event</var>'s <a>canceled flag</a> is not set, then,
448-
<a>in parallel</a>, <a>request to present an install prompt</a>
449-
with <var>event</var>.
446+
<li>If <var>showPrompt</var> is true, then, <a>in parallel</a>,
447+
<a>request to present an install prompt</a> with
448+
<var>event</var>.
450449
</li>
451450
</ol>
452451
</li>
@@ -526,6 +525,125 @@ <h2>
526525
DOM events <a>fired</a> by this specification use the <dfn>application
527526
life-cycle task source</dfn>.
528527
</p>
528+
<section data-dfn-for="BeforeInstallPromptEvent">
529+
<h3>
530+
<code>BeforeInstallPromptEvent</code> Interface
531+
</h3>
532+
<pre class="idl">
533+
[Constructor]
534+
interface BeforeInstallPromptEvent : Event {
535+
Promise&lt;PromptResponseObject&gt; prompt();
536+
};
537+
dictionary PromptResponseObject {
538+
AppBannerPromptOutcome userChoice;
539+
};
540+
</pre>
541+
<p>
542+
The <dfn>BeforeInstallPromptEvent</dfn> is dispatched prior to
543+
activating an <a>automated install prompt</a>, allowing a developer
544+
to prevent the default action for an install prompt.
545+
</p>
546+
<p>
547+
Thus, the default action of the <a>BeforeInstallPromptEvent</a> is to
548+
<a data-lt="presents an install prompt">present an automated install
549+
prompt</a> to the end-user. Canceling the default action (via
550+
<code>.preventDefault()</code>) prevents the user agent from
551+
<a data-lt="presents an install prompt">presenting an automated
552+
install prompt</a> until a later time (see
553+
<a>BeforeInstallPromptEvent.prompt</a>() method).
554+
</p>
555+
<p>
556+
An instance of a <a>BeforeInstallPromptEvent</a> has the following
557+
internal slots:
558+
</p>
559+
<dl>
560+
<dt>
561+
<dfn>[[\didPrompt]]</dfn>
562+
</dt>
563+
<dd>
564+
A boolean, initially <code>false</code>. Represents if this event
565+
was used to <a>present an install prompt</a> to the end-user.
566+
</dd>
567+
<dt>
568+
<dfn>[[\userResponsePromise]]</dfn>
569+
</dt>
570+
<dd>
571+
A promise that represents the outcome of <a>presenting an install
572+
prompt</a>.
573+
</dd>
574+
</dl>
575+
<section>
576+
<h4>
577+
<code>prompt()</code> method
578+
</h4>
579+
<p>
580+
The <dfn>prompt</dfn> method, when called, runs the following
581+
steps:
582+
</p>
583+
<ol>
584+
<li>Let <var>p</var> be a newly created promise.
585+
</li>
586+
<li>Resolve <var>p</var> with
587+
<var>this</var>.<a>[[\userResponsePromise]]</a>.
588+
</li>
589+
<li>If <var>this</var>.<a>[[\userResponsePromise]]</a> is pending:
590+
<ol>
591+
<li>If this event's <code>isTrusted</code> attribute is <code>
592+
false</code>, reject
593+
<var>this</var>.<a>[[\userResponsePromise]]</a> with
594+
<a>NotAllowedError</a>, optionally informing the developer
595+
that untrusted events can't call <code>prompt()</code>.
596+
</li>
597+
<li>Else if <var>this</var>.<a>[[\didPrompt]]</a> is
598+
<code>false</code>, then, <a>in parallel</a>, <a>request to
599+
present an install prompt</a> with this event. Wait, possibly
600+
indefinitely, for the end-user to make a choice.
601+
</li>
602+
</ol>
603+
</li>
604+
<li>Return <var>p</var>.
605+
</li>
606+
</ol>
607+
<p>
608+
To <dfn>request to present an install prompt</dfn> with
609+
<a>BeforeInstallPromptEvent</a> <var>event</var>:
610+
</p>
611+
<ol>
612+
<li>
613+
<a>Present an install prompt</a> and let <var>outcome</var> be
614+
the result.
615+
</li>
616+
<li>Let <var>responseObj</var> be a newly created
617+
<a>PromptResponseObject</a> whose <code>userChoice</code> member is
618+
the value of <var>outcome</var>.
619+
</li>
620+
<li>Resolve <var>event</var>.<a>[[\userResponsePromise]]</a> with
621+
<var>responseObj</var>.
622+
</li>
623+
</ol>
624+
</section>
625+
<section class="informative">
626+
<h4>
627+
Usage example
628+
</h4>
629+
<p>
630+
This example shows how one might prevent an automated install
631+
prompt from showing until the user has finished a set of tasks.
632+
Those tasks are represented as an array of promises, which the
633+
application "awaits" to finish before an install prompt is
634+
presented to the end-user.
635+
</p>
636+
<pre class="example" title="'beforeinstallprompt' in action">
637+
window.addEventListener("beforeinstallprompt", async (event) =&gt; {
638+
event.preventDefault();
639+
// Wait for e.g., the user to request installation from inside the app.
640+
await Promise.all(tasksThatPreventsInstallation);
641+
const { userChoice } = await event.prompt();
642+
console.info(`user choice was: ${userChoice}`);
643+
});
644+
</pre>
645+
</section>
646+
</section>
529647
<section>
530648
<h3>
531649
Extensions to the <code>Window</code> object
@@ -3507,7 +3625,7 @@ <h2>
35073625
<li>
35083626
<a href=
35093627
"https://dom.spec.whatwg.org/#concept-event-fire"><dfn data-lt=
3510-
"fire|fired">Fire an event</dfn></a>
3628+
"fire|fired|firing an event">Fire an event</dfn></a>
35113629
</li>
35123630
</ul>
35133631
<p>

0 commit comments

Comments
 (0)