Skip to content

Editorial review: Information about User-Agent reduction #41648

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Oct 28, 2025
+319 −95
Merged

Editorial review: Information about User-Agent reduction #41648

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
7f30f4a
Add information to MDN about User-Agent reduction
chrisdavidmills Oct 23, 2025
84d2df3
Add information to MDN about User-Agent reduction
chrisdavidmills Oct 23, 2025
49b2d25
Fixes for miketaylr review comments
chrisdavidmills Oct 24, 2025
807cb11
Merge branch 'main' into ua-reduction
chrisdavidmills Oct 24, 2025
940d066
remove bit that doesnt really exist
chrisdavidmills Oct 24, 2025
16832b4
Fixes for hamish review comments
chrisdavidmills Oct 27, 2025
cbd5dd8
A few more bits of clean-up
chrisdavidmills Oct 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 30 additions & 22 deletions files/en-us/web/api/navigator/appversion/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,37 +8,40 @@ browser-compat: api.Navigator.appVersion

{{APIRef("HTML DOM")}}

Returns either `"4.0"` or a string representing version information about
the browser.

> [!NOTE]
> Do not rely on this property to return the correct browser version.
The **`Navigator.appVersion`** read-only property of the {{domxref("Navigator")}} interface returns a string representing version information about the browser.

## Value

Either `"4.0"` or a string representing version information about the
browser.
A string representing version information about the browser.

## Examples
## Description

```js
alert(`Your browser version is reported as ${navigator.appVersion}`);
The `appVersion` property returns information indicating the browser version.

Note that the information returned varies significantly by browser. In some browsers, such as Chrome, this is nearly the same as the value returned by {{domxref("Navigator.userAgent")}}, with the `Mozilla/` prefix removed. For example:

```plain
5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36
```

## Notes
In other browsers, such as Firefox, this is cut down to a short string that hints at the platform/OS. For example:

```plain
5.0 (Macintosh)
```

The `window.navigator.userAgent` property may also contain the version
number (for example
`"Mozilla/5.0 (Windows; U; Win98; en-US; rv:0.9.2) Gecko/20010725 Netscape 6/6.1"`),
but you should be aware of how easy it is to change the user agent string and "spoof"
other browsers, platforms, or user agents, and also how cavalier the browser vendor
themselves are with these properties.
Theoretically this information is useful for detecting the browser and serving code to work around browser-specific bugs or lack of feature support. However, this is **unreliable** and **is not recommended** for the reasons given in [User-Agent reduction](/en-US/docs/Web/HTTP/Guides/User-agent_reduction) and [Browser detection using the user agent](/en-US/docs/Web/HTTP/Guides/Browser_detection_using_the_user_agent).

The `window.navigator.appVersion`, `window.navigator.appName` and
`window.navigator.userAgent` properties have been used in "browser sniffing"
code: scripts that attempt to find out what kind of browser you are using and adjust
pages accordingly. This lead to the current situation, where browsers had to return fake
values from these properties in order not to be locked out of some websites.
[Feature detection](/en-US/docs/Learn_web_development/Extensions/Testing/Feature_detection) is a much more reliable strategy.

## Examples

```js
console.log(navigator.appVersion);
// On Chrome, logs something like "5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36" (reduced UA string)

// On Firefox, logs something like "5.0 (Macintosh)"
```

## Specifications

Expand All @@ -47,3 +50,8 @@ values from these properties in order not to be locked out of some websites.
## Browser compatibility

{{Compat}}

## See also

- {{domxref("Navigator.userAgent")}}
- {{HTTPHeader("User-agent")}} HTTP header
33 changes: 22 additions & 11 deletions files/en-us/web/api/navigator/platform/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,29 +10,39 @@ browser-compat: api.Navigator.platform

The **`platform`** property read-only property of the {{domxref("Navigator")}} interface returns a string identifying the platform on which the user's browser is running.

## Value

A string identifying the platform on which the user's browser is running; for example:

- `"MacIntel"`
- `"Win32"`
- `"Linux x86_64"`

> [!NOTE]
> In general, you should whenever possible avoid writing code that uses methods or properties like this one to try to find out information about the user's environment, and instead write code that does [feature detection](/en-US/docs/Learn_web_development/Extensions/Testing/Feature_detection).
> On Windows, modern browsers return `"Win32"` even if running on a 64-bit version of Windows.

## Value
## Description

A string identifying the platform on which the user's browser is running; for example: `"MacIntel"`, `"Win32"`, `"Linux x86_64"`, `"Linux armv81"`.
The `platform` property indicates the platform/OS the browser is running on.

Theoretically this information is useful for detecting the browser and serving code to work around browser-specific bugs or lack of feature support. However, this is **unreliable** and **is not recommended** for the reasons given in [User-Agent reduction](/en-US/docs/Web/HTTP/Guides/User-agent_reduction) and [Browser detection using the user agent](/en-US/docs/Web/HTTP/Guides/Browser_detection_using_the_user_agent).

[Feature detection](/en-US/docs/Learn_web_development/Extensions/Testing/Feature_detection) is a much more reliable strategy.

## Examples

`navigator.platform` should almost always be avoided in favor of [feature detection](/en-US/docs/Learn_web_development/Extensions/Testing/Feature_detection). But there is one case where, among the options you could use, `navigator.platform` may be the least-bad option: When you need to show users advice about whether the modifier key for keyboard shortcuts is the `⌘` command key (found on Apple systems) rather than the `⌃` control key (on non-Apple systems):
### Determining the modifier key for the user's platform

One case where `navigator.platform` can be useful is when you need to show users advice about whether the modifier key for keyboard shortcuts is the `⌘` command key (found on Apple systems) rather than the `Ctrl` control key (on non-Apple systems):

```js
const modifierKeyPrefix =
navigator.platform.startsWith("Mac") || navigator.platform === "iPhone"
? "⌘" // command key
: "^"; // control key
: "Ctrl"; // control key
```

That is, check if `navigator.platform` starts with `"Mac"` or else is an exact match for `"iPhone"`, and then based on whether either of those is true, choose the modifier key your web application's UI will advise users to press in keyboard shortcuts.

## Usage notes

On Windows, modern browsers return `"Win32"` even if running on a 64-bit version of Windows.
This code checks if `navigator.platform` starts with `"Mac"` or else is an exact match for `"iPhone"`, and then based on whether either of those is `true`, sets a `modifierKeyPrefix` variable to the appropriate modifier key for the user's platform. This could be used in a web UI to tell users which modifier key they need when using keyboard shortcuts.

## Specifications

Expand All @@ -44,4 +54,5 @@ On Windows, modern browsers return `"Win32"` even if running on a 64-bit version

## See also

- [`navigator.userAgentData.platform`](/en-US/docs/Web/API/NavigatorUAData/platform)
- {{domxref("Navigator.userAgent")}}
- {{HTTPHeader("User-agent")}} HTTP header
47 changes: 15 additions & 32 deletions files/en-us/web/api/navigator/useragent/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,46 +8,29 @@ browser-compat: api.Navigator.userAgent

{{ApiRef("HTML DOM")}}

The **`Navigator.userAgent`** read-only property returns the
user agent string for the current browser.

> [!NOTE]
> The specification asks browsers to provide as little information via this field as
> possible. Never assume that the value of this property will stay the same in future
> versions of the same browser. Try not to use it at all, or only for current and past
> versions of a browser. New browsers may start using the same UA, or part of it, as an
> older browser: you really have no guarantee that the browser agent is indeed the one
> advertised by this property.
>
> Also keep in mind that users of a browser can change the value of this field if they
> want (UA spoofing).

Browser identification based on detecting the user agent string is
**unreliable** and **is not recommended**, as the user agent
string is user configurable. For example:

- In Firefox, you can change the preference `general.useragent.override` in
`about:config`. Some Firefox extensions do that; however, this only changes
the HTTP header that gets sent and that is returned by `navigator.userAgent`.
There might be other methods that utilize JavaScript code to identify the browser.
- Opera 6+ allows users to set the browser identification string via a menu.
The **`Navigator.userAgent`** read-only property of the {{domxref("Navigator")}} interface returns the `User-Agent` (UA) string for the current browser.

## Value

A string specifying the complete user agent string the browser
provides both in {{Glossary("HTTP")}} headers and in response to this and other related
methods on the {{domxref("Navigator")}} object.
A string specifying the browser's complete UA string.

The user agent string is built on a formal structure which can be decomposed into
several pieces of info. Each of these pieces of info comes from other navigator
properties which are also settable by the user. For more information about the
form of the user agent string, see the {{HTTPHeader("User-agent")}} HTTP header.
## Description

The `userAgent` property provides the current browser's UA string. The UA string is built on a formal structure, which can be decomposed into several pieces of information.

The browser also provides the UA string via the {{HTTPHeader("User-Agent")}} HTTP header. Parts of this information are also available in {{Glossary("HTTP")}} headers such as [User-Agent client hints](/en-US/docs/Web/HTTP/Guides/Client_hints) and other related API features such as {{domxref("Navigator.appVersion")}} and {{domxref("Navigator.platform")}}.

Theoretically this information is useful for detecting the browser and serving code to work around browser-specific bugs or lack of feature support. However, this is **unreliable** and **is not recommended** for the reasons given in [User-Agent reduction](/en-US/docs/Web/HTTP/Guides/User-agent_reduction) and [Browser detection using the user agent](/en-US/docs/Web/HTTP/Guides/Browser_detection_using_the_user_agent).

[Feature detection](/en-US/docs/Learn_web_development/Extensions/Testing/Feature_detection) is a much more reliable strategy.

## Examples

```js
alert(window.navigator.userAgent);
// alerts "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:124.0) Gecko/20100101 Firefox/124.0"
console.log(navigator.userAgent);
// On Chrome on macOS, logs something like "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36" (reduced UA string)

// On Firefox on Windows, logs something like "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:124.0) Gecko/20100101 Firefox/124.0"
```

## Specifications
Expand Down
71 changes: 60 additions & 11 deletions files/en-us/web/http/guides/client_hints/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,19 +13,41 @@ The set of "hint" headers are listed in the topic [HTTP Headers](/en-US/docs/Web

## Overview

A server must announce that it supports client hints, using the {{HTTPHeader("Accept-CH")}} header to specify the hints that it is interested in receiving.
When a client that supports client hints receives the `Accept-CH` header it can choose to append some or all of the listed client hint headers in its subsequent requests.
1. When the browser first makes a request to load a webpage, it will send the {{httpheader("User-Agent")}} header to the server.
2. Additionally, it will send the server a default set of `Sec-CH-UA-*` headers; this set of hints are referred to as the [low entropy hints](#low_entropy_hints). An Android device, for example, would send something like this:

For example, following `Accept-CH` in a response below, the client could append {{HTTPHeader("Width")}}, {{HTTPHeader("Downlink")}} and {{HTTPHeader("Sec-CH-UA")}} headers to all subsequent requests.
```http
Sec-CH-UA: "Google Chrome";v="143", "Chromium";v="143", "Not A(Brand";v="24"
Sec-CH-UA-Platform: "Android"
Sec-CH-UA-Mobile: ?1
```

```http
Accept-CH: Width, Downlink, Sec-CH-UA
```
These headers provide the following information:
- {{httpheader("Sec-CH-UA")}}: The major browser version and other brands associated with it.
- {{httpheader("Sec-CH-UA-Platform")}}: The platform.
- {{httpheader("Sec-CH-UA-Mobile")}}: A boolean that indicates whether the browser is running on a mobile device (`?1`) or not (`?0`).

3. The server can announce that it supports client hints and request additional client hints using the {{httpheader("Accept-CH")}} response header, which contains a comma-delimited list of the additional headers it would like to receive in subsequent requests. For example:

```http
Accept-CH: Sec-CH-UA-Model, Sec-CH-UA-Form-Factors
```

The default set of headers are always sent. In addition to those, we've also requested:
- {{httpheader("Sec-CH-UA-Model")}}: The device model the platform is running on.
- {{httpheader("Sec-CH-UA-Form-Factors")}}: The device's form factor(s), which indicate how the user interacts with the user-agent — the screen size, controls, etc.

This approach is efficient in that the server only requests the information that it is able to usefully handle.
It is also relatively "privacy-preserving", in that it is up to the client to decide what information it can safely share.
4. If the browser is permitted to send the server all the requested information, it will do so along with all subsequent requests until the browser or tab is closed. For example, our example Android phone might send the following updated headers with subsequent requests:

There is a small set of [low entropy client hint headers](#low_entropy_hints) that may be sent by a client even if not requested.
```http
Sec-CH-UA: "Google Chrome";v="143", "Chromium";v="143", "Not A(Brand";v="24"
Sec-CH-UA-Platform: "Android"
Sec-CH-UA-Mobile: ?1
Sec-CH-UA-Model: "Pixel 9"
Sec-CH-UA-Form-Factors: "Mobile"
```

This approach is efficient in that the server only requests the information that it is able to usefully handle. It is also relatively "privacy-preserving", in that it is up to the client to decide what information it can safely share.

> [!NOTE]
> Client hints can also be specified in HTML using the {{HTMLElement("meta")}} element with the [`http-equiv`](/en-US/docs/Web/HTML/Reference/Elements/meta/http-equiv) attribute.
Expand Down Expand Up @@ -63,7 +85,7 @@ For example, to stop requesting any hints it would send `Accept-CH` with an empt
## Low entropy hints

Client hints are broadly divided into high and low entropy hints.
The low entropy hints are those that don't give away much information that might be used to create a [fingerprinting](/en-US/docs/Glossary/Fingerprinting) for a user.
The low entropy hints are those that don't give away much information that might be used to [fingerprint](/en-US/docs/Glossary/Fingerprinting) a user.
They may be sent by default on every client request, irrespective of the server `Accept-CH` response header, depending on the permission policy.
Copy link
Collaborator

@hamishwillee hamishwillee Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't on you, but we should define what we mean by permission policy here, because normally this means a specific permission, and there is no client hints permission.

Copy link

@miketaylr miketaylr Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note: permissions and permissions policies are related, but different. And client hints do define a number of policy controlled features (which is what a permission policy controls), but you're correct that they're not powerful features (which is what permissions control).

https://w3c.github.io/webappsec-permissions-policy/
https://w3c.github.io/permissions/

Copy link
Collaborator

@hamishwillee hamishwillee Oct 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

G'day @miketaylr

Thanks. So to be clear, you're saying that I might set a policy for access to the various features using https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy with one of the linked permission names?
So by default Width is available to the current origin but if I want to to be available to some other origin in a nested context I could set Permissions-Policy: ch-width=* (say) to get permission?

The reason I ask is that the existence of this level of permissions is unknown to me, and likely unknown to the rest of MDN. The things I/we know about are listed here https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy#directives

Off hand do you know of many other similar lists of permissions. I can make sure they get added if we know about them.

Copy link
Contributor Author

@chrisdavidmills chrisdavidmills Oct 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added links to the list of permission polices in the spec for now. I'd previously added a link to the User-agent reduction article, but that section then got removed.

It isn't a perfect solution, but I don't want to document those 22 new permissions policy directives as part of this PR. I think that's a follow-up job.

Copy link
Collaborator

@hamishwillee hamishwillee Oct 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree. Not closing this as resolved yet, because I'm hoping @miketaylr might respond to my question above on "other lists".

Copy link

@miketaylr miketaylr Nov 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@hamishwillee I'm sorry to have missed the ping here!

So by default Width is available to the current origin but if I want to to be available to some other origin in a nested context I could set Permissions-Policy: ch-width=* (say) to get permission?

Yep, that's exactly correct. And yes, the discoverability for each of these permissions policy is quite low.

We (the permissions and permissions policy editors) had hoped to improve that via https://w3c.github.io/permissions-registry/, which would eventually cover permissions policies in addition to powerful features (aka, permissions)... but some folks had strong feelings against it and that was enough stop energy to just give up. For now, https://dontcallmedom.github.io/webdex/p.html#policy-controlled%20feature%40%40permissions-policy%25%25dfn is probably the best source of truth (modulo spec bugs that don't link things correctly).

Low entropy hints are:

Expand Down Expand Up @@ -108,6 +130,8 @@ Host: example.com
Sec-CH-Prefers-Reduced-Motion: "reduce"
```

In summary, `Accept-CH` requests all values you'd like for the page, while `Critical-CH` requests only the subset of values you must have on-load to properly load the page.

## Hint types

### User agent client hints
Expand Down Expand Up @@ -141,10 +165,35 @@ Headers include: {{HTTPHeader("Device-Memory")}}, {{HTTPHeader("Width")}}, {{HTT
Network client hints allow a server to vary responses based on the user's choice, network bandwidth, and latency.
Headers include: {{HTTPHeader("Save-Data")}}, {{HTTPHeader("Downlink")}}, {{HTTPHeader("ECT")}}, {{HTTPHeader("RTT")}}.

## Using client hints for responsive design

It's possible to use client hints for responsive design, for example to detect whether a mobile device or tablet is rendering your site.

An Android phone would send the following default client hints:

```http
Sec-CH-UA: "Google Chrome";v="143", "Chromium";v="143", "Not A(Brand";v="24"
Sec-CH-UA-Platform: "Android"
Sec-CH-UA-Mobile: ?1
```

An Android tablet on the other hand would send the following:

```http
Sec-CH-UA: "Google Chrome";v="143", "Chromium";v="143", "Not A(Brand";v="24"
Sec-CH-UA-Platform: "Android"
Sec-CH-UA-Mobile: ?0
```

The {{httpheader("Sec-CH-UA-Mobile")}} header can be used to determine whether the device is a mobile device or not. For hardware-specific use cases, the device model name and form factor can be requested via the high-entropy {{httpheader("Sec-CH-UA-Model")}} and {{httpheader("Sec-CH-UA-Form-Factors")}} hints.

For many responsive design needs, [media queries](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries) may be more convenient and flexible. However, there may be cases where you don't have control over the individual stylesheets of a site, and need to vary the stylesheet served based on the device signature or some kind of user preference. There are client hints that mirror some of the "user preference" media queries, such as {{httpheader("Sec-CH-Prefers-Color-Scheme")}}, {{httpheader("Sec-CH-Prefers-Reduced-Motion")}}, and {{httpheader("Sec-CH-Prefers-Reduced-Transparency")}}.

## See also

- [Client Hints headers](/en-US/docs/Web/HTTP/Reference/Headers#client_hints)
- [`Vary` HTTP Header](/en-US/docs/Web/HTTP/Reference/Headers/Vary)
- [Client Hints Infrastructure](https://wicg.github.io/client-hints-infrastructure/)
- [User Agent Client Hints API](/en-US/docs/Web/API/User-Agent_Client_Hints_API)
- [Improving user privacy and developer experience with User-Agent Client Hints](https://developer.chrome.com/docs/privacy-security/user-agent-client-hints) (developer.chrome.com)
- [Improving user privacy and developer experience with User-Agent Client Hints](https://developer.chrome.com/docs/privacy-security/user-agent-client-hints) on developer.chrome.com (2020)
- [Migrate to User-Agent Client Hints](https://web.dev/articles/migrate-to-ua-ch) on web.dev (2021)
Loading