[Version History] Notification API

[docluv]

As I mentioned in my other thread comment the way I read the explainer is the platform will be ignorant of updates unless the manifest file bits are changed. I rarely update this file. But I periodically check for updates to cached assets in my service worker. The service worker code does not change, well rarely changes. But it just checks the server for updates. It seems like it would be cleaner to have an update API method exposed in the service worker to trigger this process. I know there is a periodic sync API being batted around somewhere. But basically my mechanism is more a less a customer polyfil to that mechanism.

I have more than one pattern I use for updates, depends on the app. They are generally something like this:

• generate a file manfiest (part of server render processing) with file hashes
• generate a file manfiest (part of server render processing) with last update timestamps
• make HEAD request and compare locally cached time to server last modified times.

The manifest file approaches are similar to the concept in the explainer.

I would not go with an RSS feed per se because you have many other resource types. I prefer JSON for this as it is much cleaner. But you then get into needing server-side tooling, etc. The HEAD request is very clean and something I started doing a few months ago.

[stanleyhon]

... platform will be ignorant of updates unless the manifest file bits are changed. I rarely update this file.

Out of curiosity, would it be a lot of work for the manifest.json to be updated when you want to notify users of new features/new version etc? I don't have a great understanding into how developers like yourself are producing PWA updates.

It seems like it would be cleaner to have an update API method exposed in the service worker to trigger this process.

Something to consider here is that from my perspective, the changelog feature proposed by the explainer is more for deliberate version updates or deliberate feature announcements. I don't intend it to be used every time a PWA developer changes something.

I can see how it would be easier to programmatically always call the API every time something has changed but I don't think this matches the intention of the feature to mainly publicize major updates.

In my mind, I would see an addition to your update patterns to fit my model of changelogs as such:

• Do any existing updating procedures
• If changes are significant and the developer wants to publicize them, increment changelog->version, update the actual changelog.html or changelog.json etc. file.
  • I would also posit that updating the actual changelog file is already required if a PWA developer wants to highlight something specifically.

I would not go with an RSS feed ... I prefer JSON ...

I am curious if you have omitted talking about HTML changelogs for any reason?

In my mind, I actually expect a vast majority of PWA developers using the changelog feature to use the html approach - where they provide a webpage that we simply navigate to.

It allows the PWA developer full flexibility on the styling/feel and what information is shown. My expectation is that PWA developers can style the HTML page the same as the app - so when the changelog is requested, the changelog just feels like a native part of the app and not something separate.

In the specification, the way we present this is as options to PWA developers. If a developer wants to use this feature, they need only provide one format. And of course, the changelog feature is entirely optional too.

Is this unclear in the explainer? I can take another pass and try to make this clearer.

In the case of JSON/RSS/Atom/Other etc, the user agent/paltform would actually need to read the data, process and present it in a generic way across all PWAs which is, in my opinion, a much less nice user experience. But we wanted to provide it as an option for PWA developers who did not want to spend time styling a page and instead just wanted to provide a data payload.

[docluv]

Stanely,

Thanks for the reply.

On the HTML approach. I honestly did not think about that while writing. More mentally examining how RSS would feel.

I just recently started publishing a version # buried deep in the site about, settings or config section. More to help me know where my clients are on their devices. With caching in the service worker and CDN it can be problematic to update. So they complain when they don't get deployed updated the second they happen LOL.

Having a page is more of a best practice thing and I like that approach. I would do it. But I think the average dev or team would not follow through this unless the tooling auto created it for them. (maybe a tool for me to play with :))

I guess I have been thinking about update notifications in general lately. Just got off a call about this in fact. I hope I have not hijacked the thread with all that is going through my mind.

[docluv]

The update frequency could be an issue. I think the explainer references Uber and they comment they make numerous updates each day. I think GitHub does a few thousand a day. I never know about them, but they happen.

I guess the cadence to trigger updates is a burden the PWA owner/dev team needs to control. I mean I rarely update manifest files and is not what I considered at first. I lean on updating a version # I maintain in the service worker since I probably need it to trigger cache updates through a new installation event. But I am getting more away from that lately in favor of just periodically checking.

To pair with the idea of having an HTML resource from a URL made available you may not really need to trigger an update from the manifest file. Just add a field that points to this and make it part of the application experience within the platform.

You may need to define some standard around how this HTML looks to conform a common platform UI expection.

I hope that makes sense. :)

[stanleyhon]

With caching in the service worker and CDN it can be problematic to update. So they complain when they don't get deployed updated the second they happen LOL.

Actually, as a cool side-effect of how the this feature is currently put forward - you could even do this:

1. When deploying a new version, update the changelog->version to indicate to UAs/platforms an update is required
2. Update the actual HTML url in the manifest.json (e.g. changelog-v5.html -> changelog-v6.html)

When a customer views the changelog via the platform/UA UI, it would either show changelog-v5.html (e.g. customer not updated) or changelog-v6.html (customer up to date).

(of course this does not take into account other caching you may have implemented yourself)

I guess the cadence to trigger updates is a burden the PWA owner/dev team needs to control.

Fully agree. This is however quite challenging right now since there is no official specification on how this is supposed to work. Speaking as to how Chrome and Edge do it today - an update only occurs when the PWA is restarted.

To pair with the idea of having an HTML resource from a URL made available you may not really need to trigger an update from the manifest file.

You are correct here but we have good reason for requiring a manifest update update. One of the goals of the changelog feature is for a PWA user to see some type of notification in the non-web-content UI indicating that there are new changelog updates available to be viewed.

To clarify further, when a PWA updates because of changelog - our intention is that the UA/platform UI would show some type of "(1)" notification, drawing the user's attention to click through to view the changelog.

If we were not to mandate manifest be updated, the platform/UA would need to parse the actual HTML to know if an update has been posted. This would mean we now have need a whole bunch of specification around what the HTML page looks like. At this point, it is simpler to gate the platform/UA publicizing feature on changelog->version.

Additionally, it may occur that a manifest update is not related to changelog (a developer pushes a typo fix, or small, unimportant fix) in which case, keeping the same changelog->version number results in no changelog publicizing occurring.

This is one of the reasons for the current design of the changelog entry in the manifest.json. We reserve the top root level version field for the future when PWAs may develop more mature updating and use a sub-level changelog->version just for the feature we are discussing.

To pair with the idea of having an HTML resource ... make it part of the application experience within the platform.

I think that as the changelog explainer authors, we have no qualms with any developer who would like to take the changelog experience onto themselves as you suggest here. One reason that I still think the feature has value is because we, as the UA/platform developer, can publicize updates in ways the web content cannot.

For example, On Edge, our intention is to have some way of publicizing to the user that there have been updates to changelog information - and a user can follow UI prompts to see the changelog if desired.

You may need to define some standard around how this HTML looks to conform a common platform UI expection.

Could you clarify this part? In my mind, there should be no limitations/restrictions on how a PWA developer wants to make this page look. The way I am thinking about it is, if an Uber PWA wants to show, say uber.com/pwa/changelog.html - they would use all their existing CSS assets and style the page exactly like any other page in the PWA.

If my-first-pwa.com wants to show an unstyled page - I felt that that is their prerogative.

[docluv]

On the HTML standard I was thinking this would be something that might be rendered by the platform. Just just an URL contained within the app. Example, if I open the programs and features view in control panel I see the PWA installed and a version #. I was thinking it would somehow be consumed to view in a context like that. BTW I have no idea how it knows what version my PWA is LOL They are all 1.0.

[stanleyhon]

consumed to view in a context like that.

Oh I see, that isn't our current intention. Currently the intention is to show changelogs within the actual PWA "app" context. So in the case of HTML, it would be similar to if the PWA developer added a link on the web page itself to www.uber.com/pwa/changelog.html and a user simply clicked that link. Instead of that though, the user can access it from the PWA UA/Platform native OS UI.

BTW I have no idea how it knows what version my PWA is LOL They are all 1.0.

Currently in Chrome and Edge, 'updating' is very rudimentary (hence why I think updating is a much bigger discussion outside of the scope of this explainer). The browser simply inspects some manifest.json fields it deems important (such as start_url, theme color and some other stuff) and if those fields differ from what is stored internally an update is deemed neccesary. At the next opportunity, a reinstall of that PWA will be triggered.

It currently has nothing to do with any version numbers a PWA developer could provide. But it may in future - hence why I reserved Web App Manifest root level version.

Note: the current Web App Manifest spec has no version member at all.

[docluv]

BTW I like the notion of the browser triggering a visual queue much like the 'you can install this site' icon. Having a native mechanism to notify the user is helpful. On that thought. Do you think there might be an opportunity to add an event similar to beforeinstallprompt to trigger the update notification within the application?

Something I discuss with clients all the time is how do we know there is an update to notify the user. This would be a nice way to do that without fussing with a service worker, but rather have a pipeline triggered by the native event.

[stanleyhon]

Do you think there might be an opportunity to add an event similar to beforeinstallprompt to trigger the update notification within the application?

interesting idea. the way I've worded it in the explainer is to allow freedom for UA/platform developers to implement 'publicizing updates' however they see it. For example, Firefox may decide to publicize updates differently to Safari.

I don't think we would want to add this API in the changelog explainers because this implies that UA/platforms must show the result of calling that API in the same way. I think this suggestion would fall under a separate 'how do we do notifications in general in the PWA world'.

There are other discussions going on regarding how notifications would be surfaced but as yet there is no official specification on this. So my intention, at least for Edge, is to do a very simple, low invasive small little (1) in the browser UI to indicate changelogs have been updated and can be viewed. Once viewed, the (1) will go away forever, until a new update is triggered.

But overall I agree with your sentiment that notifications in the PWA world is also a lacking area however I don't think it's the job of the changelog explainer to address it.