Editorial review: Information about User-Agent reduction

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

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

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

@@ -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 indicating a platform, 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
 
@@ -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

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

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

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

@@ -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 is always sent; in this case, 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, 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:
 
-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.
@@ -63,8 +85,8 @@ 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.
-They may be sent by default on every client request, irrespective of the server `Accept-CH` response header, depending on the permission policy.
+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](https://wicg.github.io/client-hints-infrastructure/#policy-controlled-features).
 Low entropy hints are:
 
 - {{HTTPHeader("Save-Data")}},
@@ -75,7 +97,7 @@ Low entropy hints are:
 ## High entropy hints
 
 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.
-The decision might be based on user preferences, a permission request, or the permission policy.
+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).
 All client hints that are not low entropy hints are considered high entropy hints.
 
 ## Critical client hints
@@ -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
@@ -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)