# Web app manifest id: a stable PWA identity

> The manifest id member pins an installed PWA's identity independently of start_url, so a changed URL never creates a duplicate install.

**In one line:** `id` is the string that identifies your web application. Because it is
**separate from `start_url`**, you can later change where the app launches without the
browser treating it as a different app.

## Why id exists

Historically there was no single defined way to identify an installed web app: some browsers
derived the identity from `start_url`, while others used the manifest file's path. That made
the launch URL effectively double as the identity, so changing `start_url` could cause a
browser to treat the manifest as describing a **different** app and create a duplicate
install instead of updating the existing one.

The `id` member standardizes this. It provides an explicit identity that is independent of
`start_url`, so the launch URL and the durable identity are no longer the same value.

## How id is resolved

- `id` is a string processed as a URL **relative to the origin of `start_url`**. So
  `"id": "/?source=pwa"` for an app whose `start_url` is on `https://example.com` resolves
  to `https://example.com/?source=pwa`.
- The resolved value becomes the application's identity, which the browser uses to decide
  whether a manifest describes a previously-processed app.
- If `id` is **omitted or cannot be parsed**, the identity defaults to `start_url`. That
  default is what couples identity to the launch URL.
- Because `id` is resolved against the origin of `start_url`, it can only identify an app
  within that same origin; it cannot point at another site.

## What to set it to

- **Set `id` from the first release.** Because an omitted `id` defaults to `start_url`,
  adding or changing `id` later can change the computed identity, so choosing it before
  anyone installs avoids disturbing existing installs.
- **Keep it short and stable.** Common choices are `"id": "/"` or a marker such as
  `"id": "/?homescreen=1"`. The exact value does not matter as long as it never changes.
- **Treat `id` as permanent.** Changing it changes the app's identity, which is the
  situation `id` exists to avoid.

```json
{
  "name": "OpenPWA Demo",
  "start_url": "/app/?utm_source=pwa",
  "id": "/?homescreen=1",
  "display": "standalone"
}
```

In this manifest the app launches at `/app/?utm_source=pwa`, but its identity is the fixed
`/?homescreen=1`. You can later move the launch path without changing the identity.

## Browser & ecosystem support

The `id` member is defined in the Web App Manifest specification. Chrome added support for it
in Chrome 96. Browsers that do not process `id` keep their existing identity behavior, so
declaring `id` does not break anything where it is unsupported.

## Practical checklist

- [ ] Add an `id` to your manifest before your first public install.
- [ ] Choose a short, permanent value (`/` or a fixed marker query) and document it.
- [ ] Keep `id` stable so you can change the launch URL (`start_url`) independently.
- [ ] Avoid changing `id` after launch — it changes the app's identity.
- [ ] Remember `id` resolves against the origin of `start_url`, so a leading `/` is enough.
- [ ] Verify in Chromium DevTools → Application → Manifest that the computed app id matches what you intended.