feat(installation): define when/how to fire BIP (#524)

index.html

@@ -222,15 +222,6 @@ <h2>
         an example, the user agent could <a>install</a> the web application
         into a list of bookmarks within the user agent itself.
       </p>
-      <p>
-        An end-user can <dfn data-lt="manual installation">manually</dfn>
-        trigger the <a>installation process</a> through the browser's
-        <abbr>UI</abbr>. Alternatively, the <a>installation process</a> can
-        occur through an <dfn>automated install prompt</dfn>: that is, a
-        <abbr>UI</abbr> that the user agent presents to the user when, for
-        instance, there are sufficient <a>installability signals</a> to warrant
-        <a>installation</a> of the web application.
-      </p>
       <section data-dfn-for="AppBannerPromptOutcome">
         <h4>
           <code>AppBannerPromptOutcome</code> enum
@@ -334,11 +325,6 @@ <h3>
           denying permission to the user agent to add an icon to the homescreen
           of the device and the end-user rejecting the installation.
         </p>
-      </section>
-      <section>
-        <h3>
-          Installation
-        </h3>
         <p>
           The <dfn>steps to install the web application</dfn> are given by the
           following algorithm:
@@ -369,6 +355,67 @@ <h3>
           </li>
         </ol>
       </section>
+      <section>
+        <h2>
+          Install prompts
+        </h2>
+        <p>
+          An end-user can <dfn data-lt="manual installation">manually</dfn>
+          trigger the <a>installation process</a> through the user agent's
+          <abbr>UI</abbr>.
+        </p>
+        <p>
+          Alternatively, the <a>installation process</a> can occur through an
+          <dfn>automated install prompt</dfn>: that is, a <abbr>UI</abbr> that
+          the user agent presents to the user when, for instance, there are
+          sufficient <a>installability signals</a> to warrant
+          <a>installation</a> of the web application.
+        </p>
+        <p>
+          Prior to presenting an <a>automated install prompt</a>, a user agent
+          MUST run the <a>steps to notify before an automated install
+          prompt</a>.
+        </p>
+        <p>
+          In either case, when a user agent <dfn data-lt=
+          "present an install prompt|presenting an install prompt">presents an
+          install prompt</dfn>, the end-user's choice is represented either
+          "accepted" or "dismissed". These values are represented in the API of
+          this specification via the <a>AppBannerPromptOutcome</a> enum.
+        </p>
+        <p>
+          The <dfn>steps to notify before an automated install prompt</dfn> are
+          given by the following algorithm:
+        </p>
+        <ol>
+          <li>Wait until the <code>Document</code> of the <a>top-level browsing
+          context</a> is <a>completely loaded</a>.
+          </li>
+          <li>If there is already an <a>installation process</a> being
+          <a data-lt="present an install prompt">presented</a>, terminate this
+          algorithm.
+          </li>
+          <li>
+            <a>Queue a task</a> on the <a>application life-cycle task
+            source</a> to do the following:
+            <ol>
+              <li>Let <var>event</var> be a <a data-lt=
+              "construct a BeforeInstallPromptEvent">newly constructed</a> <a>
+                BeforeInstallPromptEvent</a> named
+                "<a>beforeinstallprompt</a>", which is cancelable.
+              </li>
+              <li>
+                <a>Fire</a> <var>event</var> at the <a>Window</a> object of the
+                <a>top-level browsing context</a>.
+              </li>
+              <li>If <var>event</var>'s <a>canceled flag</a> is not set, then,
+              <a>in parallel</a>, <a>request to present an install prompt</a>
+              with <var>event</var>.
+              </li>
+            </ol>
+          </li>
+        </ol>
+      </section>
       <section>
         <h3 id="installation-sec">
           Privacy and security considerations