[Web Install] Including computed manifest id in the API

[dmurph]

We often deal with issues where things a much harder in the user agent when given an install_url without knowing the manifest_id, and it often causes issues for admins who think they are installing X at a given install url, but things are set up correctly and it installs Y.

User agents also then are able to know things right away, like if the user has already installed that app, without needing to load the url, fetch manifest, etc.

So I would really recommend that the API includes both an install_url AND a manifest_id, allowing the caller to be extra specific about what they want, and for applicable errors to be given back to them (e.g. "The app you specified does not exist at that url")

[diekus]

@dmurph this is a great idea.

are you thinking something like adding the id as a param? Like the code below?

manifest file:

"id": "foo"

js file:

navigator.install('https://contoso.com', {id: 'foo'});

So if https://contoso.com can't be found as an installable app, then it'd check against installing https://contoso.com/foo ?

[dmurph]

I would want it required & the first argument: navigator.install('https://contoso.com/foo', 'https://contoso.com')

"Please install X, and you can find it at Y"

[dmurph]

Or if you want named arguments: navigator.install('https://contoso.com/foo', {install_url: 'https://contoso.com'});

Another way to think about this - urls change. The manifest id never changes.

[dmurph]

Some more context - this is hugely helpful in the following scenarios:

• The user has already installed that app through a different source, so you do not have to load the URL background to know information about it. This doesn't mean you won't load the url anyways, perhaps to check for updates, but it simplifies things a lot.
• Information about this app id can be cached in a database for installation or malware detection purposes, and queried immediately, instead of loading the url, which leaks data about the installation intent.
• If the install was to ever add an option to 'install SOMETHING here, even if it fails, and fix it later once the internet is working', having the correct id right away prevents a large number of edge cases & complex migration needed in the future to migrate to the correct manifest_id.
• Allows for different installation methods other than install_url in the future - the installation method or url can change, the manifest id will always remain the same to uniquely identify an app.
• Generally, the app identity can be a subtle thing that is inferred from the start_url, which has a default to the document_url, and it is not an obvious thing, but has a pivotal impact on things like updates. Forcing developers to specifies this exposes the hidden dependency / identity, so the developer actually thinks about it and specifies it.
  • Example: A site is installed w/o a manifest (if that is allowed - hypothetical behavior here). If the manifest id was never specified, if a manifest is added, it could end up with a different id due to a different start_url or id field specified. Then develeper unwittingly has two apps installed in the world, and they can never unify / update correctly
  • If the id is always specified either the site will say "oh, I'm setting my id field, what did I say it was when installing before?", or the install will now fail if the manifest ids don't match between the install API and the manifest id, and then the developer will catch the error before rolling it out to users and end up with a split userbase of apps

[dmurph]

Here is a better doc with my suggestion: https://bit.ly/web-install-api-shape-install-url

[diekus]

Hola @dmurph

We intend to make all web content installable through the API, and I believe that the proposal of having a manifest id and installURL as a best case ideal scenario is accurate.

I think both same-origin and cross-origin installs would work the same. They would have 2 shared signatures of the install method of the shape:

navigator.install(<manifest_id>, {installURL: <install url>}); (desired ideal case) navigator.install(<manifest_id>); (no installURL exists, method can be called with the manifest_id and this will follow the default fallback chain => installURL>start_url>document url)

there's also a shorthand no params version that applies to the same-origin installs that takes all default values for manifest_id and installURL, so a developer could do:

navigator.install(); and this would trigger: navigator.install(<doc url>, {installURL:<docURL>}); (in this case the app id will be the same as the document url)

In order to mitigate the issues with a developer updating a site/app with a new manifest_id then we propose a new API that allows an installed app to retrieve its id value. This would make it possible to compare ids and the developer would be able to show a message to "update" the app. This is similar behaviour to that of platform specific apps.

navigator.appId or navigator.getAppId() on installed web content.

[dmurph]

Based on all of the problems & footguns that can occur without having the manifest_id at API call time, I still strongly prefer requiring that.

Same-page install seems "less bad" to not have it, as the browser doesn't have to do more fetches to get that if it was already loaded. But - doesn't seem bad to still require it.

I had to create a another similar doc for our policy team for force-install w/o and manifest id, and why they should try to migrate to always having the manifest id: https://bit.ly/unvalidated-pwa-url-installation

[diekus]

@dmurph @amandabaker @HowardWolosky take a look at #716. This should address computed manifest_id and install_url.