Confusion between static and dynamic app shortcuts

[beaufortfrancois]

The namespace navigator.shortcuts seems to imply that app shortcuts are defined there.
However this seems to be specific to dynamic shortcuts.

I suspect web developers will expect to get both static and dynamic app shortcuts with await navigator.shortcuts.getAll(); I know I did.

We could either change the name of namespace with navigator.dynamicAppShortcuts (or something similar) or change the name of the getAllI() method with navigator.shortcuts.getDynamicShortcuts().

[tomayac]

+1, I expected this method to return everything. We might need a flag to differentiate dynamic from static shortcuts maybe.

[rayankans]

That makes sense. I'm not sure what utility exposing the static shortcuts would provide though, and wanted to avoid lengthy names. It's probably better to be explicit and include dynamic in the function names then.

I also favoured API simplicity for now as you can see, with only getters/setters. Do you folks have any thoughts on that?

[beaufortfrancois]

I like your simple approach.

To be honest, I'm not even sure getAll() is needed as I'd expect web developers to redefine all app shortcuts to make sure they're the ones expected.

[aarongustafson]

Taking a step back, why do we need to create two distinct classes of shortcuts? Why not allow the manifest-defined shortcuts to be read and modified too? Having a distinction just feels overly complex to me. Doubly so because there will be hard limits on the # that can be defined, which will vary by OS (and possibly browser).

[rayankans]

There a few reasons why, and I believe having this distinction will reduce the overall complexity.

For one thing, the web app manifest is a static representation of the manifest, and non of its fields are mutable. It would make things inconsistent to add distinction for shortcuts. Also, some platforms have the distinction between static & dynamic shortcuts (like Android). Static shortcuts need to be declared in the manifest and can't be changed. The type of shortcut used also reflects the website's use-case.

As for the shortcut hard limits, we can leave the number of shortcuts displayed as a UA decision, but enforce they appear in the order they were declared in.

[aarongustafson]

the web app manifest is a static representation of the manifest, and non of its fields are mutable.

I agree to an extent… though app icons and shortcut icons may be modified by the OS in specific ways. It’s also possible for a Service Worker to intercept (and modify) requests for & responses to external resources referenced by the Manifest, right? When the sw-launch event lands, that will also allows scripting to adjust default behavior.

I think the main issue I have with this approach is that drawing this distinction closes the door to progressive enhancement of a declarative baseline into an enhanced experience through scripting. I’ll give you an example:

Consider a media PWA. They may want to offer a generic "Continue Watching" link which would be available regardless, defined in the Manifest. When the JS API is available, however, they could replace that with "Continue Watching {{ show_name }}". Only allowing dynamic Shortcuts to be set via scripting would require the author to choose a baseline experience for everyone or an enhanced experience for a smaller audience (and no experience if there’s a JS error).

Also, some platforms have the distinction between static & dynamic shortcuts (like Android). Static shortcuts need to be declared in the manifest and can't be changed. The type of shortcut used also reflects the website's use-case.

Based on my research for v1 of this spec, I believe that Android and iOS are the only platforms that draw this distinction. If it’s a hindrance to implementing on those platforms and we generally agree that a single mutable list of Shortcuts is desirable, it seems like these implementation could consider them all dynamic shortcuts, regardless of where they are defined. (Although it’s worth noting that iOS seems to consider even dynamic shortcuts immutable.) Linux variants, macOS, and Windows (and, by extension, Electron) do not seem to draw this distinction.

I think it might make sense to put this question out to the PWA community:

Should all Shortcuts be mutable or should there be two classes of Shortcuts (static/immutable and dynamic/mutable?

Thoughts?

[rayankans]

I'm still leaning towards keeping the distinction between static/dynamic, although you do raise some very good points. My reasoning is:

• The Manifest is still a reflection of the app, I think it should be kept that way (otherwise declaring a manifest would have been a JS API instead of a link to a static file).
• If all shortcuts are dynamic, then there's little to no-point in having a shortcuts member in the manifest.
• In the media PWA scenario you described, it could still be achieved by only using the dynamic API. There's no need to declare static shortcuts and then modifying them.
• Static shortcuts offer some benefits, mainly being that they are part of the build process. On Android, this means that the shortcuts will be available to be use immediately once the PWA is installed. Using only dynamic shortcuts, the user would need to launch the app before the shortcuts become available.

But yeah, I agree that there isn't a clear-cut solution. I like the idea of getting feedback from the PWA community.

[aarongustafson]

The Manifest is still a reflection of the app, I think it should be kept that way (otherwise declaring a manifest would have been a JS API instead of a link to a static file).

Agreed on the first point, but not the second. Static/declarative provides a great baseline.

If all shortcuts are dynamic, then there's little to no-point in having a shortcuts member in the manifest.

Totally disagree on this point. Shortcuts defined in the Manifest cover the vast majority of use cases and provide a solid foundation (as I mentioned above). If it was JS API only, it would be inherently more fragile too.

In the media PWA scenario you described, it could still be achieved by only using the dynamic API. There's no need to declare static shortcuts and then modifying them.

Totally true. But it would be inherently more fragile (because it's JavaScript). Also, at least as I understand it, in creating two classes of shortcuts, you're making it impossible to interleave them in any way, which also may be undesirable and would force devs to go all in on the JS API if they wanted to have an early (as in ordering) shortcut with a dynamic label even if all the rest of the shortcuts are static.

Static shortcuts offer some benefits, mainly being that they are part of the build process. On Android, this means that the shortcuts will be available to be use immediately once the PWA is installed. Using only dynamic shortcuts, the user would need to launch the app before the shortcuts become available.

Agreed. Static offer a TON of benefits & I am not suggesting we get rid of them at all.

Question: In the Android implementation, would it be possible to pick up the manifest's shortcuts during the build process and have them implemented as dynamic shortcuts (as opposed to static shortcuts) under the hood?

[beaufortfrancois]

Can you explain why JavaScript is "fragile"?

[aarongustafson]

Can you explain why JavaScript is "fragile"?

Sure! Because our JavaScript programs are executed on the client and we don’t control that environment, we can't guarantee that the code will run or that it will run as intended. See also:

• https://kryogenix.org/code/browser/everyonehasjs.html
• https://adamsilver.io/articles/javascript-isnt-always-available-and-its-not-the-users-fault/
• https://www.aaron-gustafson.com/notebook/more-proof-we-dont-control-our-web-pages/

These are just a couple of articles discussing this lack of control and how it can expose fragility.

[rayankans]

In the Android implementation, would it be possible to pick up the manifest's shortcuts during the build process and have them implemented as dynamic shortcuts (as opposed to static shortcuts) under the hood?

Kind of. If we register all web shortcuts as dynamic android shortcuts under the hood, we'd reach the state I was telling you about where you'd only get the shortcuts after launching the PWA. Also, shortcuts v1 was already launched and uses static shortcuts under the hood, migrating away from that would also require some work.

[aarongustafson]

I'll write up the details of both approaches and then share them to make sure it's all accurate. From there, I'll put together a survey to see what the preference of web developers is.

[aarongustafson]

If we register all web shortcuts as dynamic android shortcuts under the hood, we'd reach the state I was telling you about where you'd only get the shortcuts after launching the PWA.

On desktop, installation triggers the PWA to open/re-parent. Could Android follow that model too (rather than leaving you on the website)? That would mitigate this issue, no? For what it's worth, I also find remaining in the tab (and having to hunt for the PWA icon separately) confusing.

Also, shortcuts v1 was already launched and uses static shortcuts under the hood, migrating away from that would also require some work.

While I agree that it sucks to redo work, I don't think that should be a factor in deciding the best overall approach for the web platform.

[rayankans]

Could Android follow that model too

No, users need to explicitly launch the app. There are some technical reasons for that related to how Android works.

I don't think that should be a factor in deciding the best overall approach for the web platform.

Agreed. I was just pointing it out.

[aarongustafson]

Here’s a draft post introducing the situation and setting up the poll. I originally thought about making a comparison table, but it got complicated quickly. I think if we wade too far into the weeds of implementation it will be overwhelming for folks and that end is honestly more on us than anyone else. I think it’s better to make it a (hopefully) simple question:

Do you want to have two separate classes of Shortcuts, some of which are static/immutable and some of which are dynamic/mutable or do you want to be able to access all Shortcuts from the JS API?

Feedback and corrections welcome.

[rayankans]

Thanks Aaron, this is great! I think you hit the right balance

Edit: I'd just clarify that it's about javascript edit access to manifest shortcuts in your poll. I like the way @beaufortfrancois broke it into three options here

[beaufortfrancois]

Separate: I want immutable static shortcuts and separate dynamic shortcuts accessible from JavaScript.

[beaufortfrancois]

Combined [1]: I want JavaScript read access to all shortcuts, regardless of how they are defined. And I want to be able to add/update/remove new app shortcuts dynamically. Static ones still persist as they are defined once in the PWA manifest.

[beaufortfrancois]

Combined [2]: I want JavaScript read and write access to all shortcuts, regardless of how they are defined. This means I can edit/remove app shortcuts statically defined in the PWA manifest.

[beaufortfrancois]

If we would go with Combined [2], this means that when a website creates app shortcuts dynamically, then user installs the PWA with app shortcuts defined in its manifest, the browser would remove all app shortcuts previously created in JavaScript and replace all of them with static ones from the manifest.

[aarongustafson]

In order to fit these options, I may need to heavily edit or thread several tweets together :-) Will share a link shortly.

[aarongustafson]

when a website creates app shortcuts dynamically, then user installs the PWA with app shortcuts defined in its manifest, the browser would remove all app shortcuts previously created in JavaScript and replace all of them with static ones from the manifest.

As Shortcuts are only supported for installed PWAs currently, I don’t see this as an issue because the dynamic shortcuts will never be created without the static shortcuts preexisting them.

[aarongustafson]

Attempting to piece the poll together…

How would you prefer to manage PWA Shortcuts in JavaScript?

Read/write dynamic: I want immutable "static" Shortcuts and separate "dynamic" Shortcuts I can add/update/remove via JavaScript.

Read all/write dynamic: I want JavaScript read access to all shortcuts, regardless of how they are defined and I want to be able to add/update/remove new app shortcuts dynamically. Static ones would persist as defined by the Manifest.

Read/write all: I want JavaScript access to all shortcuts, regardless of how they are defined. This means I can update/remove Shortcuts defined in the Manifest too.

• () Read/write dynamic
• () Read all/write dynamic
• () Read/write all

[rayankans]

As Shortcuts are only supported for installed PWAs currently, I don’t see this as an issue because the dynamic shortcuts will never be created without the static shortcuts preexisting them.

We'd still need to work out what would happen in that scenario if we go with the Read/write all option. It's possible that a website will use the JS API and then add shortcuts to its manifest. This is part of the API complexity I was referring to with editable manifest shortcuts.

The poll looks great to me!

[aarongustafson]

@rayankans and I chatted via email, but I thought I’d summarize the results of the Twitter poll here. The sample size was small (31 respondents), so this should be taken with a grain of salt, but I do think it helps us gauge general interest.

1. Less than 10% of respondents were keen to exclude manifest-defined (a.k.a., static) shortcuts from being visible to (or writable by) the JS API.
2. Respondents were generally split on whether manifest-defined shortcuts should be read/write (~42%) or read-only (~48%).

Given the small sample size, I think we should do a bit more investigation before deciding on a direction to go:

1. We should conduct additional research with the dev community in order to get feedback specifically on whether or not they would like to be able to modify shortcuts defined in the manifest. I will be working with the user research team at Microsoft to put something together and will run it by Rayan (and anyone else who’s interested) before we run the research study.
2. We should gather more real-world use cases from both internal and external partners. I will be kicking this off in a separate doc in a PR shortly.

Once we gather more information from developers in these two areas, we should start to see the contours of what’s needed as far as this API is concerned.

[aarongustafson]

Added the use cases here: https://github.com/rayankans/app-shortcuts/blob/master/use-cases.md

[alancutter]

What happens when the manifest updates its shortcuts after JavaScript has mutated them?