Editorial review: Information about User-Agent reduction

files/en-us/web/api/navigator/appversion/index.md

@@ -8,37 +8,50 @@ 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 some 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:
+
+```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)
+```
+
+### 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**:
+
+- 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.
 
-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.
+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 `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.
+### 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).
+
+## 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
 
@@ -47,3 +60,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

files/en-us/web/api/navigator/platform/index.md

@@ -10,29 +10,43 @@ 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
+
+The `appVersion` property returns some information indicating the platform/OS the browser is running on.
 
-A string identifying the platform on which the user's browser is running; for example: `"MacIntel"`, `"Win32"`, `"Linux x86_64"`, `"Linux armv81"`.
+### Browser detection
+
+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).
 
 ## 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):
+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
 
@@ -44,4 +58,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

files/en-us/web/api/navigator/useragent/index.md

@@ -8,46 +8,37 @@ 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.
+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.
+
+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 `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).
 
 ## 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

files/en-us/web/http/guides/client_hints/index.md

@@ -13,7 +13,22 @@ 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 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:
+
+```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
+```
+
+These `CH-UA` 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 on a mobile device (`?1`) or not (`?0`).
+
+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.
 
 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.
@@ -141,10 +156,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)