Add id member to manifest (#988)

index.html

@@ -171,6 +171,8 @@ <h2>
         </li>
         <li>[=manifest/icons=]
         </li>
+        <li>[=manifest/identity=]
+        </li>
         <li>[=manifest/lang=]
         </li>
         <li>[=manifest/name=]
@@ -232,6 +234,7 @@ <h3>
                 "sizes": "128x128"
               }],
               "scope": "/",
+              "id": "superracer",
               "start_url": "/start.html",
               "display": "fullscreen",
               "orientation": "landscape",
@@ -811,6 +814,120 @@ <h3>
           </p>
         </section>
       </section>
+      <section>
+        <h3>
+          `id` member
+        </h3>
+        <p>
+          The [=manifest's=] <code><dfn data-export="" data-dfn-for=
+          "manifest" id="identity">id</dfn></code> member is a <a>string</a> that
+          represents the <dfn>identity</dfn> for the application. 
+          The [=identity=] takes the form of a URL, which is same origin as the
+          start URL.
+        </p>
+        <p>The [=identity=] is used by user agents to uniquely identify the
+        application universally. When the user agent sees a manifest with an
+        [=identity=] that does not correspond to an already-installed
+        application, it SHOULD treat that manifest as a description of a
+        distinct application, even if it is served from the same URL as that of
+        another application. When the user agent sees a manifest where
+        |manifest|["id"] [=url/equal|equals=] the [=identity=] of an
+        already-installed application, it SHOULD be used as a signal that this
+        manifest is a replacement for the already-installed application's
+        manifest, and not a distinct application, even if it is served from a
+        different URL than the one seen previously.
+        </p>
+        <p class="note">
+          The [=identity=] can be used by a service that collects lists of web
+          applications to uniquely identify applications.
+        </p>
+        <p class="note">
+          The [=identity=] is processed like a URL but it doesn't point to a
+          resource that can be navigated to, so it's not required to be
+          [=URL/within scope=].
+        </p>
+        <p>
+          To <dfn>process the `id` member</dfn>, given [=object=]
+          |json:JSON|, [=ordered map=] |manifest:ordered map|:
+        </p>
+        <ol class="algorithm">
+          <li>Set |manifest|["id"] to |manifest|["start_url"].
+          </li>
+          <li>If the type of |json|["id"] is not [=string=], return.
+          </li>
+          <li>If |json|["id"] is the empty string, return.
+          </li>
+          <li>Let |base origin| be |manifest|["start_url"]'s [=url/origin=].</li> 
+          <li>Let |id:URL| be the result of [=URL Parser|parsing=] |json|["id"] with  |base origin| as the base URL.
+          </li>
+          <li>If |id| is failure, return.
+          </li>
+          <li>If |id| is not [=same origin=] as |manifest|["start_url"], return.
+          </li>
+          <li>Set |manifest|["id"] to |id|.</li>
+        </ol>
+        <aside class="example">
+          <p>Below table shows some example cases of the |identity| processing algorithm.</p>
+          <table class="data">
+            <tr>
+              <th>|json|["id"]</th>
+              <th>|manifest|["start_url"]</th>
+              <th>|manifest|["id"]</th>
+            </tr>
+            <tr>
+              <td><i>undefined</i></td>
+              <td>"https://example.com/my-app/start"</td>
+              <td>"https://example.com/my-app/start"</td>
+            </tr>
+            <tr>
+              <td><i>undefined</i></td>
+              <td>"https://example.com/my-app/#here"</td>
+              <td>"https://example.com/my-app/#here"</td>
+            </tr>
+            <tr>
+              <td>""</td>
+              <td>"https://example.com/my-app/start"</td>
+              <td>"https://example.com/my-app/start"</td>
+            </tr>
+            <tr>
+              <td>"/"</td>
+              <td>"https://example.com/my-app/start"</td>
+              <td>"https://example.com/"</td>
+            </tr>
+            <tr>
+              <td>"foo"</td>
+              <td>"https://example.com/my-app/start"</td>
+              <td>"https://example.com/foo"</td>
+            </tr>
+            <tr>
+              <td>"./foo"</td>
+              <td>"https://example.com/my-app/start"</td>
+              <td>"https://example.com/foo"</td>
+            </tr>
+            <tr>
+              <td>"https://example.com/foo"</td>
+              <td>"https://example.com/my-app/start"</td>
+              <td>"https://example.com/foo"</td>
+            </tr>
+            <tr>
+              <td>"https://anothersite.com/foo"</td>
+              <td>"https://example.com/my-app/start"</td>
+              <td>"https://example.com/my-app/start"</td>
+            </tr>
+            <tr>
+              <td>"😀"</td>
+              <td>"https://example.com/my-app/start"</td>
+              <td>"https://example.com/%F0%9F%98%80"</td>
+            </tr>
+          </table>
+          <p>Since [=manifest/id=] is resolved against [=manifest/start_url=]'s [=URL/origin=], providing
+          "../foo", "foo", "/foo", "./foo" all resolves to the same [=identifier=]. It is
+          As such, best practice is to use a leading "/" to be explicit that
+          the id is a root-relative url path. Also, standard
+          encoding/decoding rules are apply to the id processing algorithm, as per the [[[URL]]].
+          </p>
+        </aside>
+      </section>
       <section>
         <h3>
           `theme_color` member
@@ -1093,6 +1210,9 @@ <h3>
             <li>[=Process the `start_url` member=] passing |json|, |manifest|,
             |manifest URL|, and |document URL|.
             </li>
+            <li>[=Process the `id` member=] passing |json|, |manifest| and
+            |document URL|.
+            </li>
             <li>[=Process the `scope` member=] passing |json|, |manifest|, and
             |manifest URL|.
             </li>