Skip to content

Commit 3c3bd98

Browse files
mgiucamgiuca
committed
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.
1 parent 6fa3d47 commit 3c3bd98

File tree

1 file changed

+77
-50
lines changed

1 file changed

+77
-50
lines changed

‎index.html

Lines changed: 77 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -435,13 +435,14 @@ <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>target</var> be at <a>Window</a> object of the
439-
<a>top-level browsing context</a>.
438+
<li>Let <var>event</var> be a newly constructed
439+
<a>BeforeInstallPromptEvent</a> named
440+
<code>beforeinstallprompt</code>, with its <code>cancelable</code>
441+
attribute initialized to true.
440442
</li>
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.
443+
<li>Let <var>showPrompt</var> be the result of <a>firing</a>
444+
<var>event</var> at the <a>Window</a> object of the <a>top-level
445+
browsing context</a>.
445446
</li>
446447
<li>If <var>showPrompt</var> is true, then, <a>in parallel</a>,
447448
<a>request to present an install prompt</a> with
@@ -450,6 +451,16 @@ <h2>
450451
</ol>
451452
</li>
452453
</ol>
454+
<div class="issue">
455+
Implementations may wish to show a prompt if, and only if, the site
456+
explicitly requests it via
457+
<a><code>BeforeInstallPromptEvent.prompt()</code></a>, but not
458+
automatically without the site's approval. Is this something we want
459+
to leave to the discretion of the user agent? (This would require
460+
changing the language here, as "steps to notify before an automated
461+
install prompt" would become "steps to notify that an install prompt
462+
is available".)
463+
</div>
453464
</section>
454465
<section>
455466
<h3 id="installation-sec">
@@ -543,14 +554,22 @@ <h3>
543554
activating an <a>automated install prompt</a>, allowing a developer
544555
to prevent the default action for an install prompt.
545556
</p>
546-
<p>
547-
Thus, the default action of the <a>BeforeInstallPromptEvent</a> is to
557+
<div class="note">
558+
The default action of the <a>BeforeInstallPromptEvent</a> is to
548559
<a data-lt="presents an install prompt">present an automated install
549560
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).
561+
<a
562+
data-cite="DOM#dom-event-preventdefault"><code>preventDefault</code></a>)
563+
prevents the user agent from <a data-lt="presents an install
564+
prompt">presenting an automated install prompt</a>. The user agent is
565+
free to run <a>steps to notify before an automated install prompt</a>
566+
again at a later time.
567+
</div>
568+
<p>
569+
The <dfn>PromptResponseObject</dfn> contains the result of calling <a
570+
for="BeforeInstallPromptEvent"><code>prompt()</code></a>. It contains
571+
one member, <dfn for="PromptResponseObject">userChoice</dfn>, which
572+
states the user's chosen outcome.
554573
</p>
555574
<p>
556575
An instance of a <a>BeforeInstallPromptEvent</a> has the following
@@ -561,8 +580,8 @@ <h3>
561580
<dfn>[[\didPrompt]]</dfn>
562581
</dt>
563582
<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.
583+
A boolean, initially <code>false</code>. Represents whether this
584+
event was used to <a>present an install prompt</a> to the end-user.
566585
</dd>
567586
<dt>
568587
<dfn>[[\userResponsePromise]]</dfn>
@@ -581,27 +600,24 @@ <h4>
581600
steps:
582601
</p>
583602
<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>
589603
<li>If <var>this</var>.<a>[[\userResponsePromise]]</a> is pending:
590604
<ol>
591-
<li>If this event's <code>isTrusted</code> attribute is <code>
592-
false</code>, reject
605+
<li>If this event's <a
606+
data-cite="!DOM#dom-event-istrusted"><code>isTrusted</code></a>
607+
attribute is <code> false</code>, reject
593608
<var>this</var>.<a>[[\userResponsePromise]]</a> with
594609
<a>NotAllowedError</a>, optionally informing the developer
595610
that untrusted events can't call <code>prompt()</code>.
596611
</li>
597612
<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.
613+
<code>false</code>, set <var>this</var>.<a>[[\didPrompt]]</a>
614+
to <code>true</code>, then <a>in parallel</a>, <a>request to
615+
present an install prompt</a> with this event. Wait, possibly
616+
indefinitely, for the end-user to make a choice.
601617
</li>
602618
</ol>
603619
</li>
604-
<li>Return <var>p</var>.
620+
<li>Return <var>this</var>.<a>[[\userResponsePromise]]</a>.
605621
</li>
606622
</ol>
607623
<p>
@@ -613,12 +629,10 @@ <h4>
613629
<a>Present an install prompt</a> and let <var>outcome</var> be
614630
the result.
615631
</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>
620632
<li>Resolve <var>event</var>.<a>[[\userResponsePromise]]</a> with
621-
<var>responseObj</var>.
633+
a newly created <a>PromptResponseObject</a> whose <a
634+
for="PromptResponseObject">userChoice</a> member is the value of
635+
<var>outcome</var>.
622636
</li>
623637
</ol>
624638
</section>
@@ -628,18 +642,30 @@ <h4>
628642
</h4>
629643
<p>
630644
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.
645+
prompt from showing until the user clicks a button to install the
646+
app. In this way, the site can leave installation at the user's
647+
discretion (rather than prompting at an arbitrary time), whilst
648+
still providing a prominent UI to do so.
635649
</p>
636-
<pre class="example" title="'beforeinstallprompt' in action">
637-
window.addEventListener("beforeinstallprompt", async (event) =&gt; {
650+
<pre class="example"
651+
title="Using beforeinstallprompt to present an install button">
652+
window.addEventListener("beforeinstallprompt", event =&gt; {
653+
// Suppress automatic prompting.
638654
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}`);
655+
656+
// Show the (disabled-by-default) install button. This button
657+
// resolves the installButtonClicked promise when clicked.
658+
installButton.disabled = false;
659+
660+
// Wait for the user to click the button.
661+
installButton.addEventListener("click", async e =&gt; {
662+
// The prompt() method can only be used once.
663+
installButton.disabled = true;
664+
665+
// Show the prompt.
666+
const { userChoice } = await event.prompt();
667+
console.info(`user choice was: ${userChoice}`);
668+
});
643669
});
644670
</pre>
645671
</section>
@@ -649,9 +675,10 @@ <h3>
649675
Extensions to the <code>Window</code> object
650676
</h3>
651677
<p>
652-
The following extensions to the <dfn><code>Window</code></dfn> object
653-
specify the <a>event handler attributes</a> on which events relating
654-
to the <a>installation</a> of a web application are <a>fired</a>.
678+
The following extensions to the <dfn
679+
data-cite="!HTML#window"><code>Window</code></dfn> object specify the
680+
<a>event handler attributes</a> on which events relating to the
681+
<a>installation</a> of a web application are <a>fired</a>.
655682
</p>
656683
<pre class="idl">
657684
partial interface Window {
@@ -691,16 +718,16 @@ <h4>
691718
application</a>).
692719
</p>
693720
</section>
694-
<section>
721+
<section data-dfn-for="Window">
695722
<h4>
696723
<code>onbeforeinstallprompt</code> attribute
697724
</h4>
698725
<p>
699-
The <dfn data-dfn-for="Window">onbeforeinstallprompt</dfn> is an
700-
<a>event handler IDL attribute</a> for the
701-
"<dfn>beforeinstallprompt</dfn>" event type. The interface used for
702-
these events is the <a>BeforeInstallPromptEvent</a> interface (see
703-
the <a>steps to notify before an automated install prompt</a>).
726+
The <dfn>onbeforeinstallprompt</dfn> is an <a>event handler IDL
727+
attribute</a> for the "<dfn>beforeinstallprompt</dfn>" event type.
728+
The interface used for these events is the
729+
<a>BeforeInstallPromptEvent</a> interface (see the <a>steps to
730+
notify before an automated install prompt</a>).
704731
</p>
705732
</section>
706733
</section>
@@ -3625,7 +3652,7 @@ <h2>
36253652
<li>
36263653
<a href=
36273654
"https://dom.spec.whatwg.org/#concept-event-fire"><dfn data-lt=
3628-
"fire|fired|firing an event">Fire an event</dfn></a>
3655+
"fire|fired|firing">Fire an event</dfn></a>
36293656
</li>
36303657
</ul>
36313658
<p>

0 commit comments

Comments
 (0)