[PWA] Installation guide #25058

wbamberg · 2023-03-04T00:41:42Z

This PR adds a guide page to PWA installation. It will replace https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Installing.

Some notes and things.

this is supposed to be what Divio calls an "explanation", sort of. So I don't want it to go into how-to territory for things like making a PWA a standalone app - in fact, it would probably be good for some of these sections to link to relevant How-to guides. I think this page is about orientation and explaining what sorts of things are possible with PWAs, rather than exactly how to do them. This separation of concerns makes it easier for users who have been through the learning process to find the "how to" later on, when they need it for their project.
I've used "platform-specific" rather than "native" here, per discussions.
I haven't gone a lot into what happens on different platforms, beyond noting what's possible at all on different platforms. Perhaps I could go more into this? In particular, for example, Safari's behavior is quite different. Not sure.
likewise I haven't included a lot of screenshots - the old guide had a lot of screenshots from different platforms. I think these usually rot pretty quickly.
although the sidebar PR had these under a "main features of PWAs" heading, I've just added this directly under "Guides". This is simpler because we don't need a interstitial "Main features of PWAs" page to list these particular guides. But if we decide to do that we can always move it of course. See how it feels when we have more of them.
It would be nice to know more about Firefox behavior and requirements here. I will see if I can add that.

@captainbrosset , @estelle .

github-actions · 2023-03-04T00:44:06Z

Preview URLs

/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable

External URLs (5)

URL: /en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable
Title: Making PWAs installable

https://chromeos.dev/en/publish/pwa-in-play (1 time) (Note! This may be a new URL 👀)
https://developer.oculus.com/documentation/web/pwa-submit-app/ (1 time) (Note! This may be a new URL 👀)
https://docs.pwabuilder.com/ (1 time) (Note! This may be a new URL 👀)
https://github.com/MicrosoftEdge/Demos/tree/main/pwamp (1 time) (Note! This may be a new URL 👀)
https://learn.microsoft.com/en-us/microsoft-edge/progressive-web-apps-chromium/how-to/microsoft-store (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2023-03-08 00:45:51)

dawei-wang

A few typos

files/en-us/web/progressive_web_apps/guides/installation/index.md

Co-authored-by: dawei-wang <dawei-wang@users.noreply.github.com>

wbamberg · 2023-03-04T05:09:13Z

files/en-us/web/progressive_web_apps/guides/installation/index.md

+This technique relies on the [`beforeinstallprompt`](/en-US/docs/Web/API/Window/beforeinstallprompt_event) event, which is fired on the global [`Window`](/en-US/docs/Web/API/Window) object as soon as the browser has determined that the PWA is installable. A PWA can:
+
+- add a UI element for the user to install the PWA (for example, its own "Install" button)
+- listen for the `beforeinstallprompt` event
+- cancel the event's default behavior by calling [`preventDefault()`](/en-US/docs/Web/API/Event/preventDefault)
+- keep a reference to the [`BeforeInstallPromptEvent`](/en-US/docs/Web/API/BeforeInstallPromptEvent), and in the event handler for its own "Install" button, call the [`BeforeInstallPromptEvent.prompt()`](/en-US/docs/Web/API/BeforeInstallPromptEvent/prompt) method. This method will show the browser prompt that asks the user if they want to install the PWA.
+
+For example:
+
+```js
+window.addEventListener("beforeinstallprompt", (event) => {
+  // Don't let the default prompt go.
+  event.preventDefault();
+
+  // Instead, wait for the user to click the install button.
+  installButton.addEventListener("click", () => event.prompt());
+});
+```
+
+The `prompt()` method returns a {{jsxref("Promise")}} that resolves with a string `"accepted"` or `"dismissed"` indicating whether or not the user chose to install the PWA.


Perhaps this is too instructional and belongs in a How-to?

Yes we have the custom install flow as part of the How-To section in our shared doc. Maybe it can be here too, only shorter? In any case, we should link to the How-To here, once it exists.

Right, I'll keep something here but remove the sample code. Later on we can add links to the How-to pages for the details.

wbamberg · 2023-03-04T05:09:59Z

files/en-us/web/progressive_web_apps/guides/installation/index.md

+Once the PWA is installed its icon is shown on the device alongside any other apps that the user has installed, and clicking the icon launches the app.
+
+You can use the [`display`](/en-US/docs/Web/Manifest/display) manifest key to control the _display mode_: that is, how the PWA appears when it is launched. In particular:
+
+- `"standalone"` indicates that the PWA should look and feel like a platform-specific application, with no browser UI elements
+- `"browser"` indicates that the PWA should be opened as a new browser tab or window, just like a normal website.
+
+If the browser does not support a given display mode, `display` will fall back to a supported display mode according to a predefined sequence. The [`display_override`](/en-US/docs/Web/Manifest/display_override) enables you to redefine the fallback sequence.


This seems like an OK level of detail, and we could link to the How-to for specific instructions and example code?

Yes, I think that's a good idea. Let's add the link when we can with a leading sentence like "For more information about the various display modes and how they fallback, see ..."

captainbrosset

Love it. I left a few minor comments, but overall this looks like great content.

files/en-us/web/progressive_web_apps/guides/installation/index.md

captainbrosset · 2023-03-06T09:10:02Z

files/en-us/web/progressive_web_apps/guides/installation/index.md

+
+For a full description of every key, see the [web app manifest reference documentation](/en-US/docs/Web/Manifest).
+
+### Additional installability requirements


HTTPS and service worker are both, for now, required by all browsers to consider an app as installable. Together with manifest, these 3 criteria have been part of the PWA's DNA from the start, and I think they should each have an h3-level section like the one you used for manifest.

captainbrosset · 2023-03-06T09:11:12Z

files/en-us/web/progressive_web_apps/guides/installation/index.md

+
+If the PWA has more than one page, every page must reference the manifest in this way.
+
+The manifest contains a single JSON object containing a collection of keys, each of which defines some aspect of the PWA's appearance or behavior. Here's a rather minimal manifest, containing just two keys: `"name"` and `"icons"`.


In manifest language, we call the top-level properties members, not keys. Using members here would make things consistent with specs and other docs out there.

Ha, looking at your how-to last week I was going to complain that you use "members" instead of "keys" but then I saw that was what the spec (and most of the MDN manifest reference) uses. So yes.

captainbrosset · 2023-03-06T09:14:53Z

files/en-us/web/progressive_web_apps/guides/installation/index.md

+On mobile:
+
+- Firefox, Chrome, Edge, Opera, and Samsung Internet Browser all support installing PWAs on Android.
+- Only Safari is allowed to install PWAs on iOS.


Although this will change with the latest version of webkit. See https://webkit.org/blog/13878/web-push-for-web-apps-on-ios-and-ipados/ and search for "Third-party browser support for Add to Home Screen".

captainbrosset · 2023-03-06T09:17:02Z

files/en-us/web/progressive_web_apps/guides/installation/index.md

+This technique relies on the [`beforeinstallprompt`](/en-US/docs/Web/API/Window/beforeinstallprompt_event) event, which is fired on the global [`Window`](/en-US/docs/Web/API/Window) object as soon as the browser has determined that the PWA is installable. A PWA can:
+
+- add a UI element for the user to install the PWA (for example, its own "Install" button)
+- listen for the `beforeinstallprompt` event
+- cancel the event's default behavior by calling [`preventDefault()`](/en-US/docs/Web/API/Event/preventDefault)
+- keep a reference to the [`BeforeInstallPromptEvent`](/en-US/docs/Web/API/BeforeInstallPromptEvent), and in the event handler for its own "Install" button, call the [`BeforeInstallPromptEvent.prompt()`](/en-US/docs/Web/API/BeforeInstallPromptEvent/prompt) method. This method will show the browser prompt that asks the user if they want to install the PWA.
+
+For example:
+
+```js
+window.addEventListener("beforeinstallprompt", (event) => {
+  // Don't let the default prompt go.
+  event.preventDefault();
+
+  // Instead, wait for the user to click the install button.
+  installButton.addEventListener("click", () => event.prompt());
+});
+```
+
+The `prompt()` method returns a {{jsxref("Promise")}} that resolves with a string `"accepted"` or `"dismissed"` indicating whether or not the user chose to install the PWA.


Yes we have the custom install flow as part of the How-To section in our shared doc. Maybe it can be here too, only shorter? In any case, we should link to the How-To here, once it exists.

captainbrosset · 2023-03-06T09:18:58Z

files/en-us/web/progressive_web_apps/guides/installation/index.md

+
+### Customizing installation
+
+By default, the install prompt contains the name and icon for the PWA. If you provide values for the [`description`](/en-US/docs/Web/Manifest/description) and [`screenshots`](/en-US/docs/Web/Manifest/screenshots) manifest keys, then, on Android only, these values will be shown in the install prompt, giving the user extra context and motivation to install the PWA.


Suggested change

By default, the install prompt contains the name and icon for the PWA. If you provide values for the [`description`](/en-US/docs/Web/Manifest/description) and [`screenshots`](/en-US/docs/Web/Manifest/screenshots) manifest keys, then, on Android only, these values will be shown in the install prompt, giving the user extra context and motivation to install the PWA.

By default, the install prompt contains the name and icon for the PWA. If you provide values for the [`description`](/en-US/docs/Web/Manifest/description) and [`screenshots`](/en-US/docs/Web/Manifest/screenshots) manifest members, then, on Android only, these values will be shown in the install prompt, giving the user extra context and motivation to install the PWA.

(probably worth doing a search/replace on the entire document for keys->members).

Also, I think Chrome for desktop now also uses screenshots and description. I definitely saw it a few months ago, but now it seems disabled. So I think they're working on it behind a flag.

Yes, when I tested last week it didn't seem to be supported in Chrome desktop. I think compat is challenging in this project, and we should have a separate compat page where we document all such issues.

captainbrosset · 2023-03-06T09:20:20Z

files/en-us/web/progressive_web_apps/guides/installation/index.md

+Once the PWA is installed its icon is shown on the device alongside any other apps that the user has installed, and clicking the icon launches the app.
+
+You can use the [`display`](/en-US/docs/Web/Manifest/display) manifest key to control the _display mode_: that is, how the PWA appears when it is launched. In particular:
+
+- `"standalone"` indicates that the PWA should look and feel like a platform-specific application, with no browser UI elements
+- `"browser"` indicates that the PWA should be opened as a new browser tab or window, just like a normal website.
+
+If the browser does not support a given display mode, `display` will fall back to a supported display mode according to a predefined sequence. The [`display_override`](/en-US/docs/Web/Manifest/display_override) enables you to redefine the fallback sequence.


Yes, I think that's a good idea. Let's add the link when we can with a leading sentence like "For more information about the various display modes and how they fallback, see ..."

captainbrosset · 2023-03-06T09:24:28Z

Note that this new page should also replace https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Add_to_home_screen (we should check if there's more content on the A2HS page that needs to be saved).

Co-authored-by: Patrick Brosset <patrickbrosset@gmail.com>

captainbrosset · 2023-03-07T08:27:14Z

files/en-us/web/progressive_web_apps/guides/installation/index.md

+
+### HTTPS
+
+For a web app to be installable, it must be served over HTTPS.


It might be worth mentioning something like: "For local development purposes, browsers do not require HTTPS if the web app is accessed via the localhost domain".

files/en-us/web/progressive_web_apps/guides/installation/index.md

captainbrosset · 2023-03-07T15:17:41Z

files/en-us/web/progressive_web_apps/guides/installation/index.md

@@ -0,0 +1,142 @@
+---
+title: Installation


One additional comment: how about making this a bit longer and more explicit? I wonder if enough people will get the context from the URL and breadcrumbs on the page. I think a more self-explanatory title might be helpful. Something like "Making PWAs installable".

Not sure I love this title but I couldn't think of anything better :).

Co-authored-by: Patrick Brosset <patrickbrosset@gmail.com>

PWA installation guide

ea2de90

wbamberg requested a review from a team as a code owner March 4, 2023 00:41

wbamberg requested review from bsmth and removed request for a team March 4, 2023 00:41

github-actions bot added the Content:Other Any docs not covered by another "Content:" label label Mar 4, 2023

dawei-wang reviewed Mar 4, 2023

View reviewed changes

Apply suggestions from code review

63b0c94

Co-authored-by: dawei-wang <dawei-wang@users.noreply.github.com>

wbamberg commented Mar 4, 2023

View reviewed changes

captainbrosset requested changes Mar 6, 2023

View reviewed changes

wbamberg and others added 4 commits March 6, 2023 11:31

Apply suggestions from code review

9e5065a

Co-authored-by: Patrick Brosset <patrickbrosset@gmail.com>

keys->members

52c2c10

Cut down customised installation section

8717a81

Reorg installability requirements

deda629

wbamberg requested a review from captainbrosset March 7, 2023 04:20

captainbrosset approved these changes Mar 7, 2023

View reviewed changes

captainbrosset reviewed Mar 7, 2023

View reviewed changes

wbamberg and others added 7 commits March 7, 2023 07:52

Update files/en-us/web/progressive_web_apps/guides/installation/index.md

632979c

Co-authored-by: Patrick Brosset <patrickbrosset@gmail.com>

Update files/en-us/web/progressive_web_apps/guides/installation/index.md

b38ec9e

Co-authored-by: Patrick Brosset <patrickbrosset@gmail.com>

Apply suggestions from code review

4d4754c

Co-authored-by: Patrick Brosset <patrickbrosset@gmail.com>

More review comments

712b317

Move to reflect new title

7e322a8

Remove old version

d770c0a

Merge branch 'main' into pwa-installation-guide

725f875

wbamberg merged commit 13729b9 into mdn:main Mar 8, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[PWA] Installation guide #25058

[PWA] Installation guide #25058

wbamberg commented Mar 4, 2023

github-actions bot commented Mar 4, 2023 •

edited

Loading

dawei-wang left a comment

wbamberg Mar 4, 2023

captainbrosset Mar 6, 2023

wbamberg Mar 7, 2023

wbamberg Mar 4, 2023

captainbrosset Mar 6, 2023

captainbrosset left a comment

captainbrosset Mar 6, 2023

captainbrosset Mar 6, 2023

wbamberg Mar 6, 2023

captainbrosset Mar 6, 2023

captainbrosset Mar 6, 2023

captainbrosset Mar 6, 2023

wbamberg Mar 7, 2023

captainbrosset Mar 6, 2023

captainbrosset commented Mar 6, 2023

captainbrosset Mar 7, 2023

captainbrosset Mar 7, 2023

wbamberg Mar 8, 2023


		For a full description of every key, see the [web app manifest reference documentation](/en-US/docs/Web/Manifest).

		### Additional installability requirements


		If the PWA has more than one page, every page must reference the manifest in this way.

		The manifest contains a single JSON object containing a collection of keys, each of which defines some aspect of the PWA's appearance or behavior. Here's a rather minimal manifest, containing just two keys: `"name"` and `"icons"`.


		### Customizing installation

		By default, the install prompt contains the name and icon for the PWA. If you provide values for the [`description`](/en-US/docs/Web/Manifest/description) and [`screenshots`](/en-US/docs/Web/Manifest/screenshots) manifest keys, then, on Android only, these values will be shown in the install prompt, giving the user extra context and motivation to install the PWA.


		### HTTPS

		For a web app to be installable, it must be served over HTTPS.

[PWA] Installation guide #25058

[PWA] Installation guide #25058

Conversation

wbamberg commented Mar 4, 2023

github-actions bot commented Mar 4, 2023 • edited Loading

dawei-wang left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

captainbrosset left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

captainbrosset commented Mar 6, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Mar 4, 2023 •

edited

Loading