Editorial review: Information about User-Agent reduction #41648
Conversation
chrisdavidmills
requested review from
hamishwillee,
pepelsbey and
sideshowbarker
and removed request for
a team
chrisdavidmills
changed the title
Preview URLs (6 pages)Flaws (3)Note! 5 documents with no flaws that don't need to be listed. 🎉 URL:
External URLs (3)URL:
URL:
(comment last updated: 2025-10-27 14:36:38) |
Josh-Cena
changed the title
|
|
||
| Since these are hints, the browser may choose to ignore some of all of the server's requests for more information. In addition, the browser may be blocked from sending some or all of the information by various security features such as {{httpheader("Permissions-Policy")}}. | ||
|
|
||
| [EDITORIAL: IS THIS TRUE? I READ THIS SOMEWHERE, BUT I CAN'T FIND ANY INFO ANYWHERE ON WHAT CAN BLOCK BROWSERS FROM SENDING CLIENT HINTS. WHAT CLIENT FEATURES CAN BLOCK SENDING CLIENT HINTS?] |
There was a problem hiding this comment.
Kinda true - see https://wicg.github.io/client-hints-infrastructure/#policy-controlled-features
Most client hints can only be sent by default for the top-level site (except the default, low-entropy ones). In order to send them across cross-site frame boundaries, you have to opt in specific origins via Permissions Policy.
And besides disabling them via commandline parameters, there's no other way to prevent them from getting sent in Chrome (maybe possible via an extension? I haven't kept up with Manifest v3 changes, so not sure).
There was a problem hiding this comment.
I've removed this bit, and added info about permissions policy to the new section mentioned in the previous comment.
Looking at the link you sent gives me a sinking feeling — we don't document any of those permission-policy directives on MDN. For now, I'm going to link to the spec (which will be frowned upon, as generally we don't link to the spec if we can avoid it), and then suggest adding docs for those directives in a follow-on PR.
|
@chrisdavidmills Can you ping me directly when ready for editorial reveiw. |
Super cool, thanks for the review, @miketaylr! I'll move this one on to the editorial review stage, but feel free to chime in if you notice anything else that needs attention. |
chrisdavidmills
changed the title
There was a problem hiding this comment.
Looks good. Some comments, the most important one is probably https://github.com/mdn/content/pull/41648/files#r2464158868 - lots of duplication with the Client Hints guide.
| ## Value | ||
|
|
||
| A string representing version information about the browser. | ||
|
|
There was a problem hiding this comment.
Just a FWIW, but I'm never sure what to have in the overview, value, description to avoid irritating duplication. By way of example, here we have:
- ... returns a string representing version information about the browser.
- A string representing version information about the browser.
- ... returns information indicating the browser version.
I don't know the answer in general, but for this case I would consider making the value into "A string". Not so in the other cases though.
| ``` | ||
|
|
||
| ### 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). |
There was a problem hiding this comment.
FWIW, I like the new reduced structure and links here.
|
|
||
| ## Pre-user-agent reduction examples | ||
|
|
||
| This section provides some examples of UA strings prior to user-agent reduction: |
There was a problem hiding this comment.
Maybe
| This section provides some examples of UA strings prior to user-agent reduction: | |
| This section provides some examples of UA strings in earlier browser versions, prior to the introduction of user-agent reduction: |
| 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: |
There was a problem hiding this comment.
Perhaps useful to say "in this case", even though it is obvious.
| The default set of headers are always sent. In addition to those, we've also requested: | |
| The default set of headers are always sent. In this case we've also 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. | ||
| 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 was a problem hiding this comment.
| 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: | |
| 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: |
| 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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/
There was a problem hiding this comment.
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.
| sidebar: http | ||
| --- | ||
|
|
||
| This article explains the differences in user agent (UA) strings as a result of **User-Agent reduction**, and explains how you can access both the redacted and additional UA information if it is needed. |
There was a problem hiding this comment.
The double use of explains followed by explains reads oddly. More important is that we introduce the term we are going to describe without defining it. That's OK if it is hard to do so, but in this case it isn't.
| This article explains the differences in user agent (UA) strings as a result of **User-Agent reduction**, and explains how you can access both the redacted and additional UA information if it is needed. | |
| User-Agent reduction is a broadly accepted browser initiative to reduce the amount of privacy-sensitive information provided in the user agent (UA) strings. | |
| This article shows the differences in UA strings as a result of **User-Agent reduction**, and explains how you can access both the redacted and additional UA information if it is needed. |
| - 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. |
There was a problem hiding this comment.
The tense and tone is different in the final bullet than the others. Maybe merge them.
Note, one reason I love sentence breaks is that it makes reviewing long line updates much easier.
| - 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. | |
| - 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 historically would return fake values from such properties in order not to be locked out of some websites. | |
| Some browsers enable users to change the value of this field if they want (**UA spoofing**). |
|
|
||
| To mitigate such concerns, [supporting browsers](/en-US/docs/Web/HTTP/Reference/Headers/User-Agent#browser_compatibility) implement user-agent reduction, which updates the `User-agent` header and related API features to provide a reduced set of information. | ||
|
|
||
| ## UA string differences resulting from User-Agent reduction |
There was a problem hiding this comment.
This heading wraps - can we simplify it? Maybe
| ## UA string differences resulting from User-Agent reduction | |
| ## UA string changes after reduction |
3 participants
Description
Chromium browsers support User-Agent reduction, which means that features such as the
User-AgentHTTP header provide less-specific information in an effort to reduce their effectiveness for fingerprinting/tracking.This PR adds information on User-Agent reduction to appropriate places on MDN, as well as a new guide to cover it, and some extra information on client-side hints.
This PR is part of the final set of privacy sandbox information to be added to MDN. Much of it is being removed, but this feature is stable and will be kept, so it should be added.
Motivation
Additional details
Related issues and pull requests