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
Merged

Editorial review: Information about User-Agent reduction #41648

Show file tree
Hide file tree
Changes from 1 commit
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
18 changes: 4 additions & 14 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 @@ -16,9 +16,9 @@ A string representing version information about the browser.

## Description

The `appVersion` property returns some information indicating the browser version.
The `appVersion` property returns information indicating the browser version.

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:
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
Expand All @@ -30,19 +30,9 @@ In other browsers, such as Firefox, this is cut down to a short string that hint
5.0 (Macintosh)
```

### Browser detection
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).

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**:

- Future browsers will fix bugs and add support for new features, so your browser detection code will need to be regularly updated to avoid locking out browsers that do actually support the features you are testing for. [Feature detection](/en-US/docs/Learn_web_development/Extensions/Testing/Feature_detection) is a much more reliable strategy.
- You really have no guarantee that the user agent advertised by this property is really the one your site is loaded in. Browser vendors can basically do what they like with the UA string, and some browsers enable users to change the value of this field if they want (**UA spoofing**).
- Browser detection lead to a situation where browsers had to return fake values from such properties in order not to be locked out of some websites.

See [Browser detection using the user agent](/en-US/docs/Web/HTTP/Guides/Browser_detection_using_the_user_agent) for more information on why serving different content to different browsers is usually a bad idea, and recommendations for what you should do instead.

### User-Agent reduction

The information exposed in the `appVersion` property has historically raised [privacy](/en-US/docs/Web/Privacy) concerns — it can be used to identify a particular user agent, and can therefore be used for {{glossary("fingerprinting")}}. To mitigate such concerns, [supporting browsers](#browser_compatibility) provide a reduced set of information in their {{HTTPHeader("User-agent")}} header, the {{domxref("Navigator.userAgent", "userAgent")}} property, and other related properties. For more information, see [User-Agent reduction](/en-US/docs/Web/HTTP/Guides/User-agent_reduction).
[Feature detection](/en-US/docs/Learn_web_development/Extensions/Testing/Feature_detection) is a much more reliable strategy.

## Examples

Expand Down
14 changes: 5 additions & 9 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 @@ -23,20 +23,16 @@ A string identifying the platform on which the user's browser is running; for ex

## Description

The `appVersion` property returns some information indicating the platform/OS the browser is running on.
The `platform` property indicates the platform/OS the browser is running on.

### Browser detection
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).

Theoretically this information is useful for detecting the browser's underlying platform and serving code to work around OS-specific bugs or lack of feature support. However, this is **unreliable** and **is not recommended**. Future browsers will fix bugs and add support for new features, so your browser detection code will need to be regularly updated to avoid locking out browsers that do actually support the features you are testing for. [Feature detection](/en-US/docs/Learn_web_development/Extensions/Testing/Feature_detection) is a much more reliable strategy.

See [Browser detection using the user agent](/en-US/docs/Web/HTTP/Guides/Browser_detection_using_the_user_agent) for more information on why serving different content to different browsers is usually a bad idea, and recommendations for what you should do instead.

### User-Agent reduction

The information exposed in the `platform` property has historically raised [privacy](/en-US/docs/Web/Privacy) concerns — it can be used (in part) to identify a particular user agent, and can therefore be used for {{glossary("fingerprinting")}}. To mitigate such concerns, [supporting browsers](#browser_compatibility) provide a reduced set of information in their {{HTTPHeader("User-agent")}} header, the {{domxref("Navigator.userAgent", "userAgent")}} property, and other related properties. For more information, see [User-Agent reduction](/en-US/docs/Web/HTTP/Guides/User-agent_reduction).
[Feature detection](/en-US/docs/Learn_web_development/Extensions/Testing/Feature_detection) is a much more reliable strategy.

## Examples

### 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
Expand Down
16 changes: 4 additions & 12 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 @@ -14,23 +14,15 @@ The **`Navigator.userAgent`** read-only property of the {{domxref("Navigator")}}

A string specifying the browser's complete UA string.

The browser also provides this 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")}}.

The UA string is built on a formal structure, which can be decomposed into several pieces of information. For more information about the form of the UA string, see the {{HTTPHeader("User-agent")}} HTTP header.

## Description

The `userAgent` property provides the current browser's UA string. Theoretically this is useful for detecting the browser and serving code to work around browser-specific bugs or lack of feature support. However, browser identification based on detecting the UA string is **unreliable** and **is not recommended**:

- Future browsers will fix bugs and add support for new features, so your browser detection code will need to be regularly updated to avoid locking out browsers that do actually support the features you are testing for. [Feature detection](/en-US/docs/Learn_web_development/Extensions/Testing/Feature_detection) is a much more reliable strategy.
- You really have no guarantee that the user agent advertised by this property is really the one your site is loaded in. Browser vendors can basically do what they like with the UA string, and some browsers enable users to change the value of this field if they want (**UA spoofing**).
- Even the specification asks browsers to provide as little information via this property as possible.
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.

See [Browser detection using the user agent](/en-US/docs/Web/HTTP/Guides/Browser_detection_using_the_user_agent) for more information on why serving different content to different browsers is usually a bad idea, and recommendations for what you should do instead.
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")}}.

### User-Agent reduction
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 information exposed in the `userAgent` property has historically raised [privacy](/en-US/docs/Web/Privacy) concerns — it can be used to identify a particular user agent, and can therefore be used for {{glossary("fingerprinting")}}. To mitigate such concerns, [supporting browsers](#browser_compatibility) provide a reduced set of information in their {{HTTPHeader("User-agent")}} header, the `userAgent` property, and other related properties. For more information, see [User-Agent reduction](/en-US/docs/Web/HTTP/Guides/User-agent_reduction).
[Feature detection](/en-US/docs/Learn_web_development/Extensions/Testing/Feature_detection) is a much more reliable strategy.

## Examples

Expand Down
51 changes: 30 additions & 21 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,34 +13,41 @@ The set of "hint" headers are listed in the topic [HTTP Headers](/en-US/docs/Web

## Overview

When the browser first makes a request to load a webpage, it will send a {{httpheader("User-Agent")}} header and a default set of `Sec-CH-UA-*` headers along with the initial request. An Android device, for example, might send the following:
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:

```http
User-Agent: Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Mobile Safari/537.36
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
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
```

These `CH-UA` headers provide the following information:
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`).

- {{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 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:

In response, the server can announce that it supports client hints and specify the hints that it is interested in receiving using the {{HTTPHeader("Accept-CH")}} header (or {{HTTPHeader("Critical-CH")}}; see [Critical client hints](#critical_client_hints)).
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.
```http
Accept-CH: Sec-CH-UA-Model, Sec-CH-UA-Form-Factors
```

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.
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.

```http
Accept-CH: Width, Downlink, Sec-CH-UA
```
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:

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.
```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"
```

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.
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 @@ -78,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 @@ -123,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
Loading