Editorial review: Information about User-Agent reduction

[chrisdavidmills]

Description

Chromium browsers support User-Agent reduction, which means that features such as the User-Agent HTTP 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

[github-actions]

Preview URLs (6 pages)

• /en-US/docs/Web/API/Navigator/appVersion
• /en-US/docs/Web/API/Navigator/platform
• /en-US/docs/Web/API/Navigator/userAgent
• /en-US/docs/Web/HTTP/Guides/Client_hints
• /en-US/docs/Web/HTTP/Guides/User-agent_reduction
• /en-US/docs/Web/HTTP/Reference/Headers/User-Agent

Flaws (3)

Note! 5 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/HTTP/Guides/User-agent_reduction
Title: User-Agent reduction
Flaw count: 3

• unknown:
  • No generic content config found
  • no blog root
  • no blog root

External URLs (4)

URL: /en-US/docs/Web/HTTP/Guides/Client_hints
Title: HTTP Client hints

• https://developer.chrome.com/docs/privacy-security/user-agent-client-hints (1 time) (Note! This may be a new URL 👀)
• https://web.dev/articles/migrate-to-ua-ch (1 time) (Note! This may be a new URL 👀)
• https://wicg.github.io/client-hints-infrastructure/ (3 times) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/HTTP/Guides/User-agent_reduction
Title: User-Agent reduction

• https://developer.chrome.com/docs/privacy-security/user-agent-client-hints (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-10-28 11:18:37)

[hamishwillee]

@chrisdavidmills Can you ping me directly when ready for editorial reveiw.

[miketaylr]

LGTM - thanks Chris. Just one note, but not sure it requires any edits.

[chrisdavidmills]

LGTM - thanks Chris. Just one note, but not sure it requires any edits.

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.

[hamishwillee]

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.

[hamishwillee]

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.

[miketaylr]

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/

[hamishwillee]

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.

[chrisdavidmills]

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.

[hamishwillee]

I agree. Not closing this as resolved yet, because I'm hoping @miketaylr might respond to my question above on "other lists".

[miketaylr]

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

[hamishwillee]

Much better IMO. Few more nittish things.

[hamishwillee]

Thanks @chrisdavidmills - this holds together well IMO.

[chrisdavidmills]

Thanks @chrisdavidmills - this holds together well IMO.

Lovely, thanks @hamishwillee, and thanks to @miketaylr for the tech review.