User-Agent reduction

# Implementation status

• In origin trial Chrome 95 to 100
• In deprecation trial Chrome 100 to Chrome 112
• Register for the trial
• Chrome DevTools integration
• UA-CH Chrome platform status

# What is User-Agent reduction?

User-Agent (UA) reduction is the effort to minimize the identifying information shared in the User-Agent string which may be used for passive fingerprinting. As these changes are rolled out, all resource requests will have a reduced User-Agent header. As a result, the return values from certain Navigator interfaces will be reduced, including: navigator.userAgent, navigator.appVersion, and navigator.platform.

Web developers should prepare for the reduced User-Agent string by reviewing their site code for instances and uses of the User-Agent string. If your site relies on parsing the User-Agent string to read the device model, platform version, or full browser version, you'll need to implement the User-Agent Client Hints API.

Review the latest timeline for User-Agent reduction.

# User-Agent Client Hints (UA-CH)

User-Agent Client Hints allow access to the full set of user-agent data, but only when servers actively declare an explicit need for specific pieces of data.

By removing passively exposed user-data, we can better measure and reduce the amount of information that is intentionally exposed by request headers, JavaScript APIs, and other mechanisms.

# Why do we need reduced UA and UA-CH?

Currently, the User-Agent string broadcasts a large string of data about a user's browser, operating system, and version every HTTP request. This is problematic for two reasons:

• The granularity and abundance of detail can lead to user identification.
• The default availability of this information can lead to covert tracking.

We improve user privacy by only sharing basic information by default.

The reduced User-Agent includes the browser's brand and a significant version, where the request came from (desktop or mobile), and the platform. To access more data, User-Agent Client Hints allow you to request specific information about the user's device or conditions.

Further, the User-Agent string has grown longer and more complex, which led to error-prone string parsing. UA-CH provides structured and reliable data that is easier to interpret. Existing code which parses the UA string shouldn't break (though it will return less data), and you'll need to migrate to UA-CH if your site needs specific information information.

# How do the reduced UA and UA-CH work?

Here is a brief example of how the reduced User-Agent string and UA-CH work. For a more in-depth example, review Improving user privacy and developer experience with User-Agent Client Hints.

1. A user opens the browser and enters example.com into the address bar.
2. The browser sends a request to load the webpage.
   1. The browser includes the User-Agent header with the reduced User-Agent string. For example: User-Agent: Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/93.0.0.0 Mobile Safari/537.36
   2. The browser includes that same information in the default User-Agent Client Hint headers. For example:

      Sec-CH-UA: "Chrome"; v="93"
      Sec-CH-UA-Mobile: ?1
      Sec-CH-UA-Platform: "Android"

3. The server can ask the browser to send additional client hints with the Accept-CH response header. For example: Accept-CH: Sec-CH-UA-Arch
4. The browser applies policies and user configuration to determine what data is allowed to return to the server in subsequent request headers. For example:

   Sec-CH-UA: "Chrome"; v="93"
   Sec-CH-UA-Mobile: ?1
   Sec-CH-UA-Platform: "Android"
   Sec-CH-UA-Arch: "arm"

# Critical Client Hints

If you need a specific set of Client Hints in your initial request, you can use the Critical-CH response header. Critical-CH values must be a subset of the values requested by Accept-CH.

For example, the initial request may include a request for Device-Memory and Viewport-Width, where Device-Memory is considered critical.

GET / HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: text/html
Accept-CH: Device-Memory, Viewport-Width
Vary: Device-Memory, Viewport-Width
Critical-CH: Device-Memory

If, after processing the Accept-CH header, the client would send a critical hint, the client retries the request.

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. Refer to the Client Hints Reliability specification for more information.

# How do I prepare for reduced UA?

As we get closer to scaled availability of the reduced User-Agent string in Chrome Stable, review your site code for instances and uses of the User-Agent string. If your site relies on parsing the User-Agent string to read the device model, platform version, or full browser version, you'll need to implement the UA-CH API.

Once you've updated to the UA-CH API, you should test to ensure you get the data you expect from the User-Agent. There are three ways to test, each increasing in complexity.

Scaled availability for User-Agent reduction means the fully reduced UA string shipped on all Chrome devices. Reduction is planned to begin with a Chrome minor release in Q2 of 2022.

# Test the string locally

There are a couple of methods to test the reduced User-Agent locally:

• Enable the chrome://flags/#reduce-user-agent flag.
  • This will set your local browser to receive just the reduced user-agent string for all sites, before it becomes the default setting.
• Configure an emulated device in DevTools with the right user-agent string and client hints.
  • In the top right of DevTools, click Settings > Devices > Add custom device... to configure an emulated device with any combination of user-agent string and User-Agent Client Hints values you need.
  • In the top left of DevTools, click Toggle Device Toolbar to open the DevTools UI to emulate a device.
• Launch Chrome with the --user-agent="Custom string here".
  • Use this command line flag to run Chrome with a custom user-agent string.

# Transform the string in your site's code

If you process the existing Chrome user-agent string in your client-side or server-side code, you can transform that string to the new format to test compatibility. You can test by either overriding and replacing the string, or generating the new version and test side-by-side.

Review these User-Agent reduction snippets for example regular expressions.

# Test on real user traffic with an origin trial

Register for the Chrome origin trial to test the reduced User-Agent with your platform on real user traffic.

If you create content that is embedded onto other websites (in other words, 3rd-party content), then you can participate in a third-party origin trial and test this change across multiple sites. When you register for the Chrome origin trial, select the "third-party matching" option to allow the script to be injected when your site is embedded on third-parties.

# Engage and share feedback

• Origin trial: Register for the Chrome origin trial to opt-in for the reduced user-agent, and share your feedback.
• Demo: Try our demo of User-Agent reduction.
• GitHub: Read the UA-CH proposal, raise questions and follow discussion.
• Developer support: Ask questions and join discussions on the Privacy Sandbox Developer Support repo.

# Find out more

• Origin trial and schedule
• Improving user privacy and developer experience: an overview for web developers
• Migrate from UA string to UA-CH: a tutorial for web developers
• User-Agent snippets: code snippets to transform the current user-agent string to the reduced format for testing
• Digging into the Privacy Sandbox