You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Editorial review: Information about User-Agent reduction (#41648)
* Add information to MDN about User-Agent reduction
* Add information to MDN about User-Agent reduction
* Fixes for miketaylr review comments
* remove bit that doesnt really exist
* Fixes for hamish review comments
* A few more bits of clean-up
Returns either `"4.0"` or a string representing version information about
12
-
the browser.
13
-
14
-
> [!NOTE]
15
-
> Do not rely on this property to return the correct browser version.
11
+
The **`Navigator.appVersion`** read-only property of the {{domxref("Navigator")}} interface returns a string representing version information about the browser.
16
12
17
13
## Value
18
14
19
-
Either `"4.0"` or a string representing version information about the
20
-
browser.
15
+
A string.
21
16
22
-
## Examples
17
+
## Description
23
18
24
-
```js
25
-
alert(`Your browser version is reported as ${navigator.appVersion}`);
19
+
The `appVersion` property returns information indicating the browser version.
20
+
21
+
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:
22
+
23
+
```plain
24
+
5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36
26
25
```
27
26
28
-
## Notes
27
+
In other browsers, such as Firefox, this is cut down to a short string that hints at the platform/OS. For example:
28
+
29
+
```plain
30
+
5.0 (Macintosh)
31
+
```
29
32
30
-
The `window.navigator.userAgent` property may also contain the version
but you should be aware of how easy it is to change the user agent string and "spoof"
34
-
other browsers, platforms, or user agents, and also how cavalier the browser vendor
35
-
themselves are with these properties.
33
+
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).
36
34
37
-
The `window.navigator.appVersion`, `window.navigator.appName` and
38
-
`window.navigator.userAgent` properties have been used in "browser sniffing"
39
-
code: scripts that attempt to find out what kind of browser you are using and adjust
40
-
pages accordingly. This lead to the current situation, where browsers had to return fake
41
-
values from these properties in order not to be locked out of some websites.
35
+
[Feature detection](/en-US/docs/Learn_web_development/Extensions/Testing/Feature_detection) is a much more reliable strategy.
36
+
37
+
## Examples
38
+
39
+
```js
40
+
console.log(navigator.appVersion);
41
+
// 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)
42
+
43
+
// On Firefox, logs something like "5.0 (Macintosh)"
44
+
```
42
45
43
46
## Specifications
44
47
@@ -47,3 +50,8 @@ values from these properties in order not to be locked out of some websites.
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.
12
12
13
+
## Value
14
+
15
+
A string indicating a platform, for example:
16
+
17
+
-`"MacIntel"`
18
+
-`"Win32"`
19
+
-`"Linux x86_64"`
20
+
13
21
> [!NOTE]
14
-
> 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).
22
+
> On Windows, modern browsers return `"Win32"` even if running on a 64-bit version of Windows.
15
23
16
-
## Value
24
+
## Description
17
25
18
-
A string identifying the platform on which the user's browser is running; for example: `"MacIntel"`, `"Win32"`, `"Linux x86_64"`, `"Linux armv81"`.
26
+
The `platform` property indicates the platform/OS the browser is running on.
27
+
28
+
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).
29
+
30
+
[Feature detection](/en-US/docs/Learn_web_development/Extensions/Testing/Feature_detection) is a much more reliable strategy.
19
31
20
32
## Examples
21
33
22
-
`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):
34
+
### Determining the modifier key for the user's platform
35
+
36
+
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):
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.
32
-
33
-
## Usage notes
34
-
35
-
On Windows, modern browsers return `"Win32"` even if running on a 64-bit version of Windows.
45
+
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.
36
46
37
47
## Specifications
38
48
@@ -44,4 +54,5 @@ On Windows, modern browsers return `"Win32"` even if running on a 64-bit version
The **`Navigator.userAgent`** read-only property returns the
12
-
user agent string for the current browser.
13
-
14
-
> [!NOTE]
15
-
> The specification asks browsers to provide as little information via this field as
16
-
> possible. Never assume that the value of this property will stay the same in future
17
-
> versions of the same browser. Try not to use it at all, or only for current and past
18
-
> versions of a browser. New browsers may start using the same UA, or part of it, as an
19
-
> older browser: you really have no guarantee that the browser agent is indeed the one
20
-
> advertised by this property.
21
-
>
22
-
> Also keep in mind that users of a browser can change the value of this field if they
23
-
> want (UA spoofing).
24
-
25
-
Browser identification based on detecting the user agent string is
26
-
**unreliable** and **is not recommended**, as the user agent
27
-
string is user configurable. For example:
28
-
29
-
- In Firefox, you can change the preference `general.useragent.override` in
30
-
`about:config`. Some Firefox extensions do that; however, this only changes
31
-
the HTTP header that gets sent and that is returned by `navigator.userAgent`.
32
-
There might be other methods that utilize JavaScript code to identify the browser.
33
-
- Opera 6+ allows users to set the browser identification string via a menu.
11
+
The **`Navigator.userAgent`** read-only property of the {{domxref("Navigator")}} interface returns the `User-Agent` (UA) string for the current browser.
34
12
35
13
## Value
36
14
37
-
A string specifying the complete user agent string the browser
38
-
provides both in {{Glossary("HTTP")}} headers and in response to this and other related
39
-
methods on the {{domxref("Navigator")}} object.
15
+
A string.
40
16
41
-
The user agent string is built on a formal structure which can be decomposed into
42
-
several pieces of info. Each of these pieces of info comes from other navigator
43
-
properties which are also settable by the user. For more information about the
44
-
form of the user agent string, see the {{HTTPHeader("User-agent")}} HTTP header.
17
+
## Description
18
+
19
+
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.
20
+
21
+
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")}}.
22
+
23
+
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).
24
+
25
+
[Feature detection](/en-US/docs/Learn_web_development/Extensions/Testing/Feature_detection) is a much more reliable strategy.
// 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)
32
+
33
+
// On Firefox on Windows, logs something like "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:124.0) Gecko/20100101 Firefox/124.0"
Copy file name to clipboardExpand all lines: files/en-us/web/http/guides/client_hints/index.md
+62-13Lines changed: 62 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,19 +13,41 @@ The set of "hint" headers are listed in the topic [HTTP Headers](/en-US/docs/Web
13
13
14
14
## Overview
15
15
16
-
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.
17
-
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.
16
+
1. When the browser first makes a request to load a webpage, it will send the {{httpheader("User-Agent")}} header to the server.
17
+
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:
18
18
19
-
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.
- {{httpheader("Sec-CH-UA")}}: The major browser version and other brands associated with it.
27
+
- {{httpheader("Sec-CH-UA-Platform")}}: The platform.
28
+
- {{httpheader("Sec-CH-UA-Mobile")}}: A boolean that indicates whether the browser is running on a mobile device (`?1`) or not (`?0`).
29
+
30
+
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:
The default set of headers is always sent; in this case, we've also requested:
37
+
- {{httpheader("Sec-CH-UA-Model")}}: The device model the platform is running on.
38
+
- {{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.
24
39
25
-
This approach is efficient in that the server only requests the information that it is able to usefully handle.
26
-
It is also relatively "privacy-preserving", in that it is up to the client to decide what information it can safely share.
40
+
4. If the browser is permitted, it will send the requested headers in 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:
27
41
28
-
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.
29
51
30
52
> [!NOTE]
31
53
> 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.
@@ -63,8 +85,8 @@ For example, to stop requesting any hints it would send `Accept-CH` with an empt
63
85
## Low entropy hints
64
86
65
87
Client hints are broadly divided into high and low entropy hints.
66
-
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.
67
-
They may be sent by default on every client request, irrespective of the server `Accept-CH` response header, depending on the permission policy.
88
+
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.
89
+
They may be sent by default on every client request, irrespective of the server `Accept-CH` response header, depending on the [permission policy](https://wicg.github.io/client-hints-infrastructure/#policy-controlled-features).
68
90
Low entropy hints are:
69
91
70
92
- {{HTTPHeader("Save-Data")}},
@@ -75,7 +97,7 @@ Low entropy hints are:
75
97
## High entropy hints
76
98
77
99
The high entropy hints are those that have the potential to give away more information that can be used for user fingerprinting, and therefore are gated in such a way that the user agent can make a decision whether to provide them.
78
-
The decision might be based on user preferences, a permission request, or the permission policy.
100
+
The decision might be based on user preferences, a permission request, or a [permission policy](https://wicg.github.io/client-hints-infrastructure/#policy-controlled-features).
79
101
All client hints that are not low entropy hints are considered high entropy hints.
80
102
81
103
## Critical client hints
@@ -108,6 +130,8 @@ Host: example.com
108
130
Sec-CH-Prefers-Reduced-Motion: "reduce"
109
131
```
110
132
133
+
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.
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.
189
+
190
+
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")}}.
-[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)
198
+
-[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)
199
+
-[Migrate to User-Agent Client Hints](https://web.dev/articles/migrate-to-ua-ch) on web.dev (2021)
0 commit comments