[PWA] Add a guide on offline and background operation

[wbamberg]

This is a guide page to the APIs that enable a PWA to work better offline and to have some ability to work in the background. It's supposed to help introduce people to this collection of APIs and give them an ideas of the kinds of things that are possible here. I'd expect it would link to reference docs or how-tos for full details as these are made available.

It's quite long but I'd prefer not to break it up if possible: I think it's quite helpful to have them all introduced together.

Maybe it needs a "See also" at the end? Could link to the various web.dev articles on these APIs. In the course of writing this I made a few updates to our reference docs, but we could certainly use more detailed docs on MDN here.

I expect this will replace:
https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Offline_Service_workers
https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Re-engageable_Notifications_Push

@captainbrosset , @estelle .

[github-actions]

Preview URLs

• /en-US/docs/Web/Progressive_web_apps/Guides/Offline_and_background_operation

External URLs (8)

URL: /en-US/docs/Web/Progressive_web_apps/Guides/Offline_and_background_operation
Title: Offline and background operation

• https://datatracker.ietf.org/doc/html/draft-thomson-webpush-vapid-02 (1 time) (Note! This may be a new URL 👀)
• https://datatracker.ietf.org/doc/html/rfc8030 (2 times) (Note! This may be a new URL 👀)
• https://developer.chrome.com/articles/periodic-background-sync/ (1 time) (Note! This may be a new URL 👀)
• https://developer.chrome.com/blog/background-fetch/ (1 time) (Note! This may be a new URL 👀)
• https://developer.chrome.com/blog/background-sync/ (1 time) (Note! This may be a new URL 👀)
• https://github.com/web-push-libs/web-push (2 times) (Note! This may be a new URL 👀)
• https://web.dev/notifications/ (1 time) (Note! This may be a new URL 👀)
• https://web.dev/pwa-with-offline-streaming/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2023-03-29 17:43:42)

[hamishwillee]

One real "for example" might be nice.

[wbamberg]

@captainbrosset , do you have a good example for this? I thought about messaging, but I don't think notifications are a very good fit for that.

[captainbrosset]

I think most chat apps do push notifications. In fact they very often nag you after installation to enable push notifications.

[hamishwillee]

Is this a Permissions-Policy permission, a user-grantable permission, or both?

• Worth saying and linking to the top level page
• I don't see any documentation on this or periodic-background-sync - is there a plan to create it? I do see background-sync here: https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API
• I've been trying to create a proper target for the Permissions API versions of the permissions to link to - for example for midi, the link should be here https://developer.mozilla.org/en-US/docs/Web/API/Navigator/requestMIDIAccess#security_requirements or https://developer.mozilla.org/en-US/docs/Web/API/Web_MIDI_API#security_requirements - perhaps not in this PR but I think this pattern is good to follow.

[hamishwillee]

Same question for the others below

[wbamberg]

Is this a Permissions-Policy permission, a user-grantable permission, or both?

Worth saying and linking to the top level page

Doesn't it do this in the paragraph before the bullet list?

In this section we'll outline these steps. Several of these APIs require explicit user permission, and various other restrictions and design choices to help protect users.

Do we need to repeat it for each bullet?

Yes, we should make sure permissions are properly documented in the reference pages. Should we wait for openwebdocs/project#146, when we might know where to put it? I don't think this page should have to block on that, either way.

[hamishwillee]

Yes you do say it is a user-permission - sorry. Yes adding permissions should not block this PR.

I might still explicitly add the permission type. It does feel repetitive, but it is completely unambiguous.

Suggested change

	- The Background Fetch API requires the `"background-fetch"` permission, and the browser displays the ongoing progress of the fetch operation, enabling the user to cancel it.
	- The Background Fetch API requires the `"background-fetch"` user permission, and the browser displays the ongoing progress of the fetch operation, enabling the user to cancel it.

Just my two bits, I would not wait on openwebdocs/project#146. I'd copy the model of https://developer.mozilla.org/en-US/docs/Web/API/Web_MIDI_API#security_requirements and add a "Security Requirements" section to https://developer.mozilla.org/en-US/docs/Web/API/Background_Fetch_API (and others) that mentions the permissions.

Why? Well, you know the security considerations already so it is best to catch them now where they are most likely to be seen in reference. Even if I'm wrong about where they end up, I know that if you follow a pattern like this it will be easier to move to the "final" version when that is agreed. Because this is the kind of pattern people have been following, if at all. By people I mean me and @Elchi3

[wbamberg]

Yes you do say it is a user-permission - sorry. Yes adding permissions should not block this PR.

I might still explicitly add the permission type. It does feel repetitive, but it is completely unambiguous.

Fair enough -> 3b54d56.

Just my two bits, I would not wait on openwebdocs/project#146. I'd copy the model of https://developer.mozilla.org/en-US/docs/Web/API/Web_MIDI_API#security_requirements and add a "Security Requirements" section to https://developer.mozilla.org/en-US/docs/Web/API/Background_Fetch_API (and others) that mentions the permissions.

Why? Well, you know the security considerations already so it is best to catch them now where they are most likely to be seen in reference. Even if I'm wrong about where they end up, I know that if you follow a pattern like this it will be easier to move to the "final" version when that is agreed. Because this is the kind of pattern people have been following, if at all. By people I mean me and @Elchi3

Yeah, makes sense. But not in this PR. Doing this work has made me realise how important having consistent docs for permissions and other security requirements is.

[hamishwillee]

Doing this work has made me realise how important having consistent docs for permissions and other security requirements is.

Yes, I had a similar epiphany when looking at Web Midi API and Permissions API. Hopefully the project codifies this soon.

[hamishwillee]

@wbamberg My two bits.

1. This is much better than the documents it replaces. It's a good overview of all the options at about the right level.

   • I did add one comment on push notifications because that didn't have a concrete example, and after the can be annoying comment, I was wondering what cases might be considered reasonable. Perhaps the chat message from a user in contacts?

2. At the start you defined the following examples of things you might want to do:

   • A music app enables the user to stream music while online, but can download tracks in the background and then continue to play while the user is offline.
   • The user composes a long email, presses "Send", and then loses network connectivity. The device sends the email in the background, as soon as the network is available again.
   • The user's chat app receives a message from one of their contacts, and although the app is not open, it displays a badge on the app icon to let the user know they have a new message.

   It occurred to me you you might want a summary that maps these use cases to the APIs that meet them. Perhaps instead be explicit in the examples you use in each section "this allows users to meet the use case in the introduction Xxxx".

3. Is there a missing use case of a fully offline application that updates from a server as the content changes - or is this just an extension of the other ideas? I'm thinking of things like offline wikipedia app.

4. How does sidebar work in PWAs? i.e. do you need to add this explicitly in some way?

Approving, but leaving to allow you to get additional review.

[wbamberg]

Thanks for the review!

@wbamberg My two bits.

1. This is much better than the documents it replaces. It's a good overview of all the options at about the right level.
   
   * I did add one comment on push notifications because that didn't have a concrete example, and after the can be annoying comment, I was wondering what cases might be considered reasonable. Perhaps the chat message from a user in contacts?

Commented above inline, but again here: yes, I wanted a use case but couldn't think of a good one. A notification seems excessive for a chat message (a badge seems better). I asked Patrick above if he had any good ideas.

2. At the start you defined the following examples of things you might want to do:
   > * A music app enables the user to stream music while online, but can download tracks in the background and then continue to play while the user is offline.
   > * The user composes a long email, presses "Send", and then loses network connectivity. The device sends the email in the background, as soon as the network is available again.
   > * The user's chat app receives a message from one of their contacts, and although the app is not open, it displays a badge on the app icon to let the user know they have a new message.
   
   
   It occurred to me you you might want a summary that maps these use cases to the APIs that meet them. Perhaps instead be explicit in the examples you use in each section "this allows users to meet the use case in the introduction Xxxx".

I have tried a bit to do this am struggling to find a way I like. But I'll keep thinking.

3. Is there a missing use case of a fully offline application that updates from a server as the content changes - or is this just an extension of the other ideas? I'm thinking of things like offline wikipedia app.

Is this covered by the "news app" in http://localhost:5042/en-US/docs/Web/Progressive_web_apps/Guides/Offline_and_background_operation#periodic_background_sync ? If not, what's the difference? I'd say offline Wikipedia would be a good case for periodic sync.

4. How does sidebar work in PWAs? i.e. do you need to add this explicitly in some way?

Draft PWA sidebar is at mdn/yari#8238 but we're not landing it until at least most of the pages are in place. And yes, we have to add guide pages explicitly (because of no support for weight :).

[captainbrosset]

Approved with a few comments/suggestions.

[captainbrosset]

Kino does use backgroundFetch, but you have to enable it first: in the app, go to the settings page (top right corner gear icon in the app), and enable the third setting.

I just tested in Chrome and Edge with the app installed on Windows, and both did show the browser download UI. See the Chrome example here:

So I think what happened last time is that I tested without the background fetch option, which is why I thought there was no browser UI indicating the download.

Yeah, I can see this being confusing. I mean technically it is "the browser" even if the app is installed, right? Because the browser is acting as a kind of virtual machine. At least that's my understanding! But I can see it being confusing. Do you think "device" would be OK here?

You are correct, it is the browser that runs the app, even when it's installed. And how much of it is shown depends on the display-mode. It's set to minimal-ui for the kino app, which is why, when installed on desktop, there's a back button and a refresh button displayed in the title bar. With standalone, no UI from the browser would be visible, but the browser would still be running the app. Just not with its usual "chrome".

I think we should write something about this in the PWA docs. Not in this guide, but perhaps in the installation guide.

We could rephrase slightly: "The browser that's running the app will display a persistent UI element reminding the user that the request is ongoing, giving them the chance..."

[captainbrosset]

I think most chat apps do push notifications. In fact they very often nag you after installation to enable push notifications.

[captainbrosset]

I had no idea that the push event and the user notification were tied like this. I thought a service worker could very well receive push notifications from a server without, then, displaying notifications. In my head, this was useful to display badges, or just update something in IndexedDB, etc.

Do you know what is the reason for this? Maybe privacy or security? If so, consider adding something at the end of the paragraph like "...but no browsers support this for privacy reasons".

[wbamberg]

Yeah, there's an excellent piece on this here: https://web.dev/push-notifications-subscribing-a-user/#uservisibleonly-options .

From my reading, in Chrome anyway, if the SW has not shown a notification by the time waitUntil() resolves, then the browser shows some generic notification. I haven't tested this though! Maybe I should. It's hard to test though.

Anyway, added a bit here: 881aaa5.