Uniquely identifying PWAs with the web app manifest id property

Pete LePage

When the user installs your PWA, the browser needs a way to uniquely identify the PWA. But, until recently, the web app manifest spec didn't explicitly define a way to uniquely identify a PWA, leaving browsers to decide and leading to different implementations. In some browsers, the start_url is used, while in others, the path to the manifest file is used, making it impossible to update either of those fields.

To solve this issue, there's a new optional id property in the web app manifest spec, that allows you to explicitly define the identifier used for your PWA. Adding the id property to the manifest removes the dependency on the start_url or the location of the manifest, and makes it possible for them to be updated in the future.

What does the id property do?

The id property represents the identity of the PWA to the browser. When the browser sees a manifest that does not have an identity that matches an already installed PWA, it will treat it as a new PWA, even if it is served from the same URL as another PWA. But if it sees a manifest with an identity that matches the already installed PWA, it will treat that as the installed PWA.

Browser support

Support for the id property landed in Chrome 96.

What should I do if I have an app without an id?

There is nothing you need to do, and nothing will break if you don't add an id to your web app manifest (as long as the start_url and the manifest path remains the same). To future-proof your PWA, you can add an id property to your web app manifest.

How do I determine and set my id?

The safest, and the most accurate, way to determine the id for a PWA is to check the value calculated by Chrome.

  1. Using Chrome 96 or higher, open the Manifest pane of the Application panel in DevTools.
  2. A note below the Computed App Id property will appear when the id is not specified in the web app manifest file.
  3. Copy the id value shown in the note (see screenshot below).
  4. Add an id property to the web app manifest using the id value shown in the note.

Computed App Id in DevTools Application panel.

{
  ...
  id: "/?homescreen=1",
  start_url: "/?homescreen=1",
  ...
}

What if I don't set an id?

Don't worry, nothing will break. Starting in Chrome 96, the browser will generate an id if there is not one in the manifest based on the start_url in the web app manifest.

Adding an id to the web app manifest makes it possible to change the start_url and the manifest path (if and only if their particular origin stays the same!), because the browser will identify the PWA based on the specified id, rather than the start_url or manifest path.

How do I test this?

To test the behavior, follow these steps:

  1. Install the PWA.
  2. Open about://web-app-internals/ and check the manifest_id and start_url property for the installed PWA.
  3. Add an id property to your web app manifest following the steps in How do I determine and set my id above.
  4. Restart the browser using chrome://restart, launch the PWA from about://apps, then close the PWA to force the manifest file to refresh.
  5. Open about://web-app-internals/ and check the manifest_id property for the installed PWA to verify it hasn't changed.
  6. Change the start_url in the web app manifest.
  7. Restart the browser using chrome://restart, launch the PWA from about://apps, then close the PWA to force the manifest file to refresh.
  8. Open about://web-app-internals/ and check the start_url property for the installed PWA to verify it has been updated as expected.

Additional resources