updates the explainer to require an app id (#843)

* same-origin web install can install any content on the web but requires an id.

Author: diekus

WebInstall/explainer_same_domain.md

@@ -39,14 +39,14 @@ The site can trigger its own installation.
 
 The current way of supporting installation is vai the `onbeforeinstallprompt` event, which only works in browsers that have a prompting UI affordace. 
 
-The `navigator.install()` method allows a imperative way to install web content, and works for UAs that prompt and don't prompt:
+The `navigator.install` method allows a imperative way to install web content, and works for UAs that prompt and don't prompt:
 
 ```javascript
 /* tries to install the current domain */
 const installApp = async () => {
     if (!navigator.install) return; // api not supported
     try {
-        await navigator.install();
+        await navigator.install('content_id_123');
     } catch(err) {
         switch(err.name){
             case 'AbortError':
@@ -59,11 +59,11 @@ const installApp = async () => {
 
 ![Same domain install flow](./samedomaininstall.png) 
 
-The **`navigator.install()` method can overlap with some functionality of `beforeinstallprompt` for same-origin installation**. When the method is called it will trigger the UA to prompt for the installation of an application. This is analogous to when the end user clicks on an affordance that the UA might have to inform the user of installing. On Edge, Chrome (desktop) and Samsung Internet (mobile), this would be when the user clicks on the 'app available' banner or related UX that appears on the omnibox of the browser. For browsers that do not implement prompting, the expected behaviour is analogous to their installation paradigm. For example, in Safari (desktop) the behaviour might be that it shows a dialog to add the content to the dock as an app.
+The **`navigator.install` method can overlap with some functionality of `beforeinstallprompt` for same-origin installation**. When the method is called it will trigger the UA to prompt for the installation of an application. This is analogous to when the end user clicks on an affordance that the UA might have to inform the user of installing. On Edge, Chrome (desktop) and Samsung Internet (mobile), this would be when the user clicks on the 'app available' banner or related UX that appears on the omnibox of the browser. For browsers that do not implement prompting, the expected behaviour is analogous to their installation paradigm. For example, in Safari (desktop) the behaviour might be that it shows a dialog to add the content to the dock as an app.
 
-On UAs that support prompting, the threshold for `navigator.install()` to resolve on same-origin installations uses the same checks that `onbeforeinstallprompt` currently has for prompting (if required by the UA). The promise doesn't resolve unless the *installability criteria* is met. *Note that the criteria defined by UAs varies and can be that there is NO criteria*.
+On UAs that support prompting, the threshold for `navigator.install` to resolve on same-origin installations uses the same checks that `onbeforeinstallprompt` currently has for prompting (if required by the UA). The promise doesn't resolve unless the *installability criteria* is met. *Note that the criteria defined by UAs varies and can be that there is NO criteria*.
 
-When called on the same domain, the **`install()` method will trigger/open the prompt for installation the same way that using `onbeforeinstallprompt` does right now for browser that prompts.** If there is an error with the installation, then the promise returns a `DOMException` of type 'AbortError'. 
+When called on the same domain, the **`install` method will trigger/open the prompt for installation the same way that using `onbeforeinstallprompt` does right now for browser that prompts.** If there is an error with the installation, then the promise returns a `DOMException` of type 'AbortError'. 
 
 *Any same-origin content can be installed even if it is **NOT** an application.*
 
@@ -72,11 +72,11 @@ When called on the same domain, the **`install()` method will trigger/open the p
 
 ### The `navigator.install` method
 
-To install a web site/app, the site/app would use the promise-based method`navigator.install(manifest_id[[, install_url], <params>])`. This method will:
+To install a web site/app, the site/app would use the promise-based method`navigator.install(<id>[[, install_url], <params>])`. This method will:
 
 * Resolve when an installation was completed.
     * The success value will be an object that contains:
-     	*  `manifest_id`: computed `manifest_id` of the installed application.
+     	*  Computed `id`: computed `id` of the installed web content. This is the `id` that is passed on as a parameter to reference the installed content. 
 * Be rejected if the prompt is not shown or if the app installation did not complete. It'll reject with a [`DOMException`](https://developer.mozilla.org/en-US/docs/Web/API/DOMException) value of:
     * `AbortError`: The installation was not completed.
 
@@ -85,21 +85,19 @@ To install a web site/app, the site/app would use the promise-based method`navig
 
 const installApp = async () => {
     try{
-        const value = await navigator.install();
+        const value = await navigator.install('content_id_123');
     }
     catch(err){console.error(err.message)}
 };
 
 ```
-
 ![Promises resolve/reject flow](./installPromises.png) 
 
 #### **Signatures of the `install` method (same-origin)**
 The same-origin part of the  Web Install API consists of the extension to the navigator interface with the install method. The install method can be used in several different ways. There is no difference in behaviour when this is called from a standalone window or a tab.
 
-1. `navigator.install([<params>])`: The method receives no parameters and tries to install the current origin as an app. Note that `manifest_id` *is required* for the installation and if the method is called without one it will use the *default* manifest id of the web content. The default manifest id resolves to the `start_url` if defined, or the document url if not defined.
-
-2. `navigator.install(manifest_id[[, install_url], <params>])`: The method takes a manifest id and optional install url and tries to install the current origin as an app. If the content being installed has a manifest file, this must match the value in the manifest file. If there is no manifest file present, it must match the document url. The call can also receive an object with parameters that it can use to customize a same domain installation. These parameters alter how the app is installed and are defined in an object. More information about the parameters is found in the [Parameters](#parameters) subsection of this specification.
+1. `navigator.install(id[[, install_url], <params>])`: The method takes an id (and optional install url) and tries to install the current origin. If the content being installed has a manifest file, this `id` must match the value in the manifest file. If there is no manifest file present, this `id` will act as the app id for the installed content. This is relevant since if the installed content were to be given a manifest file and made into an application, there is a way to automatically update the app going forward. 
+The call can also receive an object with parameters that it can use to customize a same domain installation. These parameters alter how the app is installed and are defined in an object. More information about the parameters is found in the [Parameters](#parameters) subsection of this specification.
 
 #### **Parameters**
 
@@ -119,7 +117,7 @@ To install a same domain web site/app, the process is as follows:
 
 * **`navigator.install` and manifest file's `prefer_related_applications`:** When the `related_applications` and `prefer_related_applications` key/values are present in the manifest, the UA should try to handoff the install to the prefered catalog. If this is not possible then it fallback to a default UA install.
 
-* **`navigator.install()` and getInstalledRelatedApps():** If a web app tries to install itself (same domain install) it can first use the `getInstalledRelatedApps()` to check if it is already installed and hide the installation UI.
+* **`navigator.install` and getInstalledRelatedApps():** If a web app tries to install itself (same domain install) it can first use the `getInstalledRelatedApps()` to check if it is already installed and hide the installation UI.
 
 ```javascript
 
@@ -134,7 +132,7 @@ relatedApps.forEach((app) => {
 ## Installability criteria
 In order for an application/site to be installed, it must comply with *installability criteria*. **This criteria is entirely up to the UA**, can *vary depending on the installation target*, and can be optional. 
 
-Modern browsers allow for different degrees of installation of different types of content, ranging from traditional web sites all the way up to Progressive Web Apps. **The core functionality of the same-origin version of the API is that it allows to install *anything* initiated with a user action**.  
+Modern browsers allow for different degrees of installation of different types of content, ranging from traditional web sites all the way up to Progressive Web Apps. **The core functionality of the same-origin version of the API is that it allows to install *any content*, as long as it is initiated with a user action**. Note that even though there are no installability requirements, the `navigator.install` method does require an id to install *any content*.
 
 A user agent might decide to have only the requirement of HTTPS to allow installation of a web site, or may need as well a manifest file and/or service worker to install a web app or might not require anything at all, allowing the user to install any content they wish.