Review comment updates

files/en-us/web/api/beforeinstallpromptevent/beforeinstallpromptevent/index.md

@@ -37,5 +37,5 @@ new BeforeInstallPromptEvent(type, eventInitDict)
 
 ## See also
 
-- [Making PWAs installable](/en-US/docs/Web/Progressive_web_apps/Guides/Making_pwas_installable)
+- [Making PWAs installable](/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable)
 - [How to provide your own in-app install experience](https://web.dev/customize-install/) on web.dev (May 19, 2021)

files/en-us/web/api/beforeinstallpromptevent/index.md

@@ -32,25 +32,48 @@ _Inherits properties from its parent, {{domxref("Event")}}._
 
 ## Instance methods
 
-- {{domxref("BeforeInstallPromptEvent.prompt()")}} {{Experimental_Inline}}
-  - : Allows a developer to show the install prompt at a time of their own choosing. This method returns a {{jsxref("Promise")}} that resolves to an object describing the user's choice when they were prompted to install the app.
+- {{domxref("BeforeInstallPromptEvent.prompt()")}}{{Non-standard_Inline}} {{Experimental_Inline}}
+  - : Show a prompt asking the user if they want to install the app. This method returns a {{jsxref("Promise")}} that resolves to an object describing the user's choice when they were prompted to install the app.
 
-## Example
+## Examples
 
-In this example we listen for the {{domxref("Window.beforeinstallprompt_event", "beforeinstallprompt")}} event. When it fires, we cancel the default behavior, which prevents the browser's built-in install prompt from showing. Next we show the app's custom install UI, and when the user clicks this UI, we call `prompt()` on the `BeforeInstallPromptEvent` that was passed into the `beforeinstallprompt` listener.
+In the following example an app provides its own install button, which has an `id` of `"install"`. Initially the button is hidden.
+
+```html
+<button id="install" hidden>Install</button>
+```
+
+The `beforeinstallprompt` handler:
+
+- Cancels the event, which prevents the browser displaying its own install UI on some platforms
+- Assigns the `BeforeInstallPromptEvent` object to a variable, so it can be used later
+- Reveals the app's install button.
+
+```js
+let installPrompt = null;
+const installButton = document.querySelector("#install");
+
+window.addEventListener("beforeinstallprompt", (event) => {
+  event.preventDefault();
+  installPrompt = event;
+  installButton.removeAttribute("hidden");
+});
+```
+
+When clicked, the app's install button:
+
+- Calls the {{domxref("BeforeInstallPromptEvent.prompt()", "prompt()")}} method of the stored event object, to trigger the installation prompt.
+- Resets its state by clearing the `installPrompt` variable and hiding itself again.
 
 ```js
-window.addEventListener("beforeinstallprompt", (beforeInstallPromptEvent) => {
-  // Prevent browser's own prompt display
-  beforeInstallPromptEvent.preventDefault();
-  // Show the app's custom install button
-  const customInstallButton = document.querySelector("#install");
-  customInstallButton.hidden = false;
-  // Prompt the user to install when they press the custom install button
-  customInstallButton.addEventListener("click", async () => {
-    const result = await beforeInstallPromptEvent.prompt();
-    console.log(`Outcome: ${result.outcome}`);
-  });
+installButton.addEventListener("click", async () => {
+  if (!installPrompt) {
+    return;
+  }
+  const result = await installPrompt.prompt();
+  console.log(`Install prompt was: ${result.outcome}`);
+  installPrompt = null;
+  installButton.setAttribute("hidden", "");
 });
 ```
 
@@ -60,5 +83,5 @@ window.addEventListener("beforeinstallprompt", (beforeInstallPromptEvent) => {
 
 ## See also
 
-- [Making PWAs installable](/en-US/docs/Web/Progressive_web_apps/Guides/Making_pwas_installable)
+- [Making PWAs installable](/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable)
 - [How to provide your own in-app install experience](https://web.dev/customize-install/) on web.dev (May 19, 2021)

files/en-us/web/api/beforeinstallpromptevent/platforms/index.md

@@ -23,5 +23,5 @@ An array of strings, in which each string identifies a target platform for the i
 
 ## See also
 
-- [Making PWAs installable](/en-US/docs/Web/Progressive_web_apps/Guides/Making_pwas_installable)
+- [Making PWAs installable](/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable)
 - [How to provide your own in-app install experience](https://web.dev/customize-install/) on web.dev (May 19, 2021)

files/en-us/web/api/beforeinstallpromptevent/prompt/index.md

@@ -11,9 +11,10 @@ browser-compat: api.BeforeInstallPromptEvent.prompt
 
 {{APIRef}}{{SeeCompatTable}}{{Non-standard_header}}
 
-The **`prompt()`** method of the
-{{domxref("BeforeInstallPromptEvent")}} interface allows a developer to show the
-install prompt at a time of their own choosing.
+The **`prompt()`** method of the {{domxref("BeforeInstallPromptEvent")}} interface allows a developer to show the
+install prompt at a time of their own choosing. Typically this will be called in the event handler for the app's custom install UI.
+
+This method must be called in the event handler for a user action (such as a button click) and may only be called once on a given `BeforeInstallPromptEvent` instance.
 
 ## Syntax
 
@@ -40,28 +41,13 @@ A {{jsxref("Promise")}} resolving to an object containing the following properti
 
 ## Examples
 
-In this example we listen for the {{domxref("Window.beforeinstallprompt_event", "beforeinstallprompt")}} event. When it fires, we cancel the default behavior, which prevents the browser's built-in install prompt from showing. Next we show the app's custom install UI, and when the user clicks this UI, we call `prompt()` on the `BeforeInstallPromptEvent` that was passed into the `beforeinstallprompt` listener.
-
-```js
-window.addEventListener("beforeinstallprompt", (beforeInstallPromptEvent) => {
-  // Prevent browser's own prompt display
-  beforeInstallPromptEvent.preventDefault();
-  // Show the app's custom install button
-  const customInstallButton = document.querySelector("#install");
-  customInstallButton.hidden = false;
-  // Prompt the user to install when they press the custom install button
-  customInstallButton.addEventListener("click", async () => {
-    const result = await beforeInstallPromptEvent.prompt();
-    console.log(`Outcome: ${result.outcome}`);
-  });
-});
-```
+See the [example for the `BeforeInstallPromptEvent` interface](/en-US/docs/Web/API/BeforeInstallPromptEvent#examples).
 
 ## Browser compatibility
 
 {{Compat}}
 
 ## See also
 
-- [Making PWAs installable](/en-US/docs/Web/Progressive_web_apps/Guides/Making_pwas_installable)
+- [Making PWAs installable](/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable)
 - [How to provide your own in-app install experience](https://web.dev/customize-install/) on web.dev (May 19, 2021)

files/en-us/web/api/beforeinstallpromptevent/userchoice/index.md

@@ -32,5 +32,5 @@ A {{jsxref("Promise")}} which resolves to an object containing two properties:
 
 ## See also
 
-- [Making PWAs installable](/en-US/docs/Web/Progressive_web_apps/Guides/Making_pwas_installable)
+- [Making PWAs installable](/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable)
 - [How to provide your own in-app install experience](https://web.dev/customize-install/) on web.dev (May 19, 2021)

files/en-us/web/api/window/beforeinstallprompt_event/index.md

@@ -8,7 +8,18 @@ browser-compat: api.Window.beforeinstallprompt_event
 
 {{APIRef}}
 
-The **`beforeinstallprompt`** event fires on devices when a user is about to be prompted to "install" a web application. It may be saved for later and used to prompt the user at a more suitable time.
+The **`beforeinstallprompt`** event fires when the browser has detected that a website can be [installed as a Progressive Web App](/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable).
+
+There's no guaranteed time this event is fired, but it usually happens on page load.
+
+The typical use for this event is when a web app wants to provide its own in-app UI inviting the user to install the app, rather than the generic one provided by the browser. This enables the app to provide more context about the app, explaining to the user why they might want to install it.
+
+In this scenario, the handler for this event will:
+
+- Keep a reference to the {{domxref("BeforeInstallPromptEvent")}} object that's passed into it
+- Reveal its in-app installation UI (this should be hidden by default, because not all browsers will support intallation).
+
+When the user uses the in-app installation UI to install the app, the in-app installation UI calls the {{domxref("BeforeInstallPromptEvent.prompt()", "prompt()")}} method of the retained `BeforeInstallPromptEvent` object to show the installation prompt.
 
 ## Syntax
 
@@ -30,27 +41,55 @@ A {{domxref("BeforeInstallPromptEvent")}}. Inherits from {{domxref("Event")}}.
 
 _Inherits properties from its parent, {{domxref("Event")}}._
 
-- {{domxref("BeforeInstallPromptEvent.platforms")}} {{ReadOnlyInline}}
-  - : Returns an array of strings containing the platforms on which the event was dispatched. This is provided for user agents that want to present a choice of versions to the user such as, for example, "web" or "play" which would allow the user to choose between a web version or an Android version.
-- {{domxref("BeforeInstallPromptEvent.userChoice")}} {{ReadOnlyInline}}
-  - : Returns a {{jsxref("Promise")}} that resolves to a string containing either "accepted" or "dismissed".
+- {{domxref("BeforeInstallPromptEvent.platforms")}} {{ReadOnlyInline}}{{Non-standard_Inline}} {{Experimental_Inline}}
+  - : Returns an array of string items containing the platforms on which the event was dispatched. This is provided for user agents that want to present a choice of versions to the user such as, for example, "web" or "play" which would allow the user to choose between a web version or an Android version.
+- {{domxref("BeforeInstallPromptEvent.userChoice")}} {{ReadOnlyInline}}{{Non-standard_Inline}} {{Experimental_Inline}}
+  - : Returns a {{jsxref("Promise")}} that resolves to an object describing the user's choice when they were prompted to install the app.
+
+## Event methods
+
+- {{domxref("BeforeInstallPromptEvent.prompt()")}}{{Non-standard_Inline}} {{Experimental_Inline}}
+  - : Show a prompt asking the user if they want to install the app. This method returns a {{jsxref("Promise")}} that resolves to an object describing the user's choice when they were prompted to install the app.
+
+## Examples
 
-## Example
+In the following example an app provides its own install button, which has an `id` of `"install"`. Initially the button is hidden.
 
-The following example uses the `beforeinstallprompt` event to make an
-install button operable, by using the event inside a click handler.
+```html
+<button id="install" hidden>Install</button>
+```
+
+The `beforeinstallprompt` handler:
+
+- Cancels the event, which prevents the browser displaying its own install UI on some platforms
+- Assigns the `BeforeInstallPromptEvent` object to a variable, so it can be used later
+- Reveals the app's install button.
 
 ```js
-window.addEventListener("beforeinstallprompt", (beforeInstallPromptEvent) => {
-  beforeInstallPromptEvent.preventDefault(); // Prevents immediate prompt display
+let installPrompt = null;
+const installButton = document.querySelector("#install");
+
+window.addEventListener("beforeinstallprompt", (event) => {
+  event.preventDefault();
+  installPrompt = event;
+  installButton.removeAttribute("hidden");
+});
+```
 
-  // Shows prompt after a user clicks an "install" button
-  installButton.addEventListener("click", (mouseEvent) => {
-    // you should not use the MouseEvent here, obviously
-    beforeInstallPromptEvent.prompt();
-  });
+When clicked, the app's install button:
 
-  installButton.hidden = false; // Make button operable
+- Calls the {{domxref("BeforeInstallPromptEvent.prompt()", "prompt()")}} method of the stored event object, to trigger the installation prompt.
+- Resets its state by clearing the `installPrompt` variable and hiding itself again.
+
+```js
+installButton.addEventListener("click", async () => {
+  if (!installPrompt) {
+    return;
+  }
+  const result = await installPrompt.prompt();
+  console.log(`Install prompt was: ${result.outcome}`);
+  installPrompt = null;
+  installButton.setAttribute("hidden", "");
 });
 ```