# related_applications and prefer_related_applications

> How the manifest's related_applications array points to platform-specific apps (platform, url, id), and how the prefer_related_applications boolean hints browsers to offer a native app instead of the web app.

**In one line:** `related_applications` is an array pointing to
platform-specific applications related to your web app — each entry needs a
`platform` plus a `url` and/or an `id` — and the boolean
`prefer_related_applications` (omitting it behaves the same as `false`) hints to browsers whether to
offer one of those related apps instead of the web app itself.

## `related_applications`

MDN describes it as being "used to specify one or more applications that are
related to your web application. These may be platform-specific applications
or Progressive Web Apps." Each entry is an object that "must include a
`platform` property and a `url` or an `id` (or both)":

- **`platform`** — a string identifying where the app can be found. Documented
  examples include `amazon` (Amazon App Store), `play` (Google Play Store),
  `windows` (Windows Store), and `webapp` (for a Progressive Web App).
- **`url`** *(optional)* — the URL where the platform-specific application can
  be found. If omitted, `id` must be provided.
- **`id`** *(optional)* — the ID representing the application on the specified
  platform. If omitted, `url` must be provided.

```json
"related_applications": [
  {
    "platform": "play",
    "url": "https://play.google.com/store/apps/details?id=com.example.app1",
    "id": "com.example.app1"
  },
  {
    "platform": "windows",
    "url": "https://apps.microsoft.com/store/detail/example-app1/9WZDNCRFHVJL"
  }
]
```

A `webapp`-platform entry can reference the PWA itself:

```json
"related_applications": [
  { "platform": "webapp", "id": "com.example.app1" }
]
```

MDN also notes the relationship is unidirectional — "the native apps are not
required to reference your web app in return" — and that this data enables
`Navigator.getInstalledRelatedApps()`, letting your web app check whether a
platform-specific version, or the web app itself, is already installed on the
device.

## `prefer_related_applications`

This boolean "provide[s] a hint to browsers whether to prefer installing
native applications specified in the `related_applications` manifest member
over your web application." Per MDN:

- **`true`** — browsers may prompt users to install one of the
  `related_applications` entries instead of the web app.
- **`false` or omitted** — browsers prefer installing the web app over the
  related native applications.

```json
{
  "prefer_related_applications": true,
  "related_applications": [
    { "platform": "play", "id": "com.example.hiking-app" }
  ]
}
```

MDN flags a Chromium-specific behavior: "For Chromium-based browsers,
`prefer_related_applications` should be set to `false` or omitted to make your
web app installable."

## Status

Both members are documented by MDN as **Experimental** and **Limited
availability** ("not Baseline because it does not work in some of the most
widely-used browsers"), per the Manifest Incubations spec.

## Practical checklist

- [ ] Give every `related_applications` entry a `platform`, and at least one
      of `url` / `id`.
- [ ] Add a `webapp`-platform entry referencing your own PWA if you want
      `getInstalledRelatedApps()` to detect the web app itself.
- [ ] For Chromium-based browsers, MDN recommends leaving
      `prefer_related_applications` `false` (or omitting it) to make your web
      app installable there.
- [ ] Check current browser support before relying on either member in
      production — MDN marks both experimental with limited availability.