Re: [w3c/manifest] Feat(events): add BeforeInstallPromptEvent (#520)

mgiuca commented on this pull request.



> +          "construct a BeforeInstallPromptEvent">constructed</a>:
+        </p>
+        <dl>
+          <dt>
+            <dfn>[[\didPrompt]]</dfn>
+          </dt>
+          <dd>
+            A boolean, initially <code>false</code>. Represents if this event
+            was used to <a>present an install prompt</a> to the end-user.
+          </dd>
+          <dt>
+            <dfn>[[\userResponsePromise]]</dfn>
+          </dt>
+          <dd>
+            A promise, which resolves with a <a>PromptResponseObject</a>, which
+            represent the outcome of <a>presenting an install prompt</a>.

represents

> +                <a>in parallel</a>, <a>request to present an install prompt</a>
+                with this event. Wait, possibly indefinitely, for the end-user
+                to make a choice.
+                </li>
+              </ol>
+            </li>
+            <li>Return <var>p</var>.
+            </li>
+          </ol>
+          <p>
+            To <dfn>request to present an install prompt</dfn> with
+            <a>BeforeInstallPromptEvent</a> <var>event</var>:
+          </p>
+          <ol>
+            <li>
+              <a>Present an install prompt</a> and <var>outcome</var> be the

and *let* outcome be the result

> +        </section>
+        <section class="informative">
+          <h4>
+            Usage example
+          </h4>
+          <p>
+            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.
+          </p>
+          <pre class="example" title="'beforeinstallprompt' in action">
+            window.addEventListener("beforeinstallprompt", async (event) =&gt; {
+              event.preventDefault();
+              // await e.g., user composing an email...

This comment is a bit confusing. I think I understand it (if the user is composing an email in the application you would wait until they finish the task before prompting). But I think that's just a bit confusing of a use case and the primary use case for this is not to avoid interrupting the user, but to present in-context UI for prompting.

So how about:
```js
// Wait for e.g., the user to request installation from inside the app.
```

> +            Usage example
+          </h4>
+          <p>
+            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.
+          </p>
+          <pre class="example" title="'beforeinstallprompt' in action">
+            window.addEventListener("beforeinstallprompt", async (event) =&gt; {
+              event.preventDefault();
+              // await e.g., user composing an email...
+              await Promise.all(tasksThatPreventsInstallation);
+              const { userChoice } = await event.prompt();
+              console.info(`user selected: ${userChoice}`);

How about `"user choice was: ${uc}"` because the grammar would be weird of "user selected: accepted".

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/manifest/pull/520#pullrequestreview-7918923