User-Agent reduction

# Implementation status

• Overview of User-Agent reduction
• Origin trial Chrome 95 to 103
• Deprecation trial Chrome 103 to Chrome 112
• Chrome DevTools integration
• Review the UA-CH Chrome platform status

User-Agent Client Hints API documentation is available on MDN.

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

A user opens the browser and enters example.com into the address bar:

1. 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/98.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="98"
      Sec-CH-UA-Mobile: ?1
      Sec-CH-UA-Platform: "Android"

2. The server can ask the browser to send additional client hints with the Accept-CH response header, such as the device model. For example: Accept-CH: Sec-CH-UA, Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA-Model
3. 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-Model: "Pixel 2"

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

# Detect tablet devices with the UA-CH API

As the line between mobile, tablet, and desktop devices continues to become less distinct and dynamic form factors are more common (folding screens, switching between laptop and tablet mode), it's advisable to use responsive design and feature detection to present an appropriate user interface.

However, information provided by the browser for both the User-Agent string and User-Agent Client Hints comes from the same source, so the same forms of logic should work.

For example, if this pattern is checked on the UA string:

• Phone pattern: 'Android' + 'Chrome/[.0-9]* Mobile'
• Tablet pattern: 'Android' + 'Chrome/[.0-9]* (?!Mobile)'

The matching default UA-CH headers interface may be checked:

• Phone pattern: Sec-CH-UA-Platform: "Android", Sec-CH-UA-Mobile: ?1
• Tablet pattern: Sec-CH-UA-Platform: "Android", Sec-CH-UA-Mobile: ?0

Or the equivalent JavaScript interface:

• Phone pattern: navigator.userAgentData.platform === 'Android' && navigator.userAgentData.mobile === true
• Tablet pattern: navigator.userAgentData.platform === 'Android' && navigator.userAgentData.mobile === false

For hardware-specific use-cases, the device model name can be requested via the high entropy Sec-CH-UA-Model hint.

# How do I prepare for reduced UA?

As we get closer to scaled availability of the reduced User-Agent string, 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.

# Support for Client Hints and critical hints

There are three default Client Hints returned to the server, including browser name and major version, a boolean which indicates if the browser is on a mobile device, and the operating system name. These are sent after the TLS handshake. These are already available and supported in your browser.

However, there may be some times when you need to retrieve critical information for your site to render.

# Optimize critical hints

A Transport Layer Security protocol (TLS) handshake is the first step to create a secure connection between the browser and web server. Without an intervention, the Critical-CH response header was designed to tell the browser to immediately retry the request if the first one was sent without a critical hint.

To optimize critical hints (Critical-CH header), you must intercept this handshake and provide a model for Client Hints. These steps may be complex, and require advanced knowledge.

The ACCEPT_CH HTTP/2 and HTTP/3 frames, combined with the TLS ALPS extension, are a connection-level optimization to deliver the server’s Client Hint preferences in time for the first HTTP request. These require complex configuration, and we recommend only using this for truly critical information. BoringSSL (a fork of OpenSSL) helps you work with Google’s experimental features in Chromium. At this time, ALPS is only implemented in BoringSSL.

If you need to use critical hints, refer to our guide on critical hints reliability and optimization.

# FAQ

# How long will hints specified via the Accept-CH header be sent?

Hints specified via the Accept-CH header will be sent for the duration of the browser session or until a different set of hints are specified.

# Does UA-CH work with HTTP/2 and HTTP/3?

UA-CH works with both HTTP/2 and HTTP/3 connections.

# Do subdomains (and CNAMEs) require a top-level page Permissions-Policy to access high entropy UA-CH?

High-entropy UA-CH on request headers are restricted on cross-origin requests regardless of how that origin is defined on the DNS side. Delegation must be handled via Permissions-Policy for any cross-origin subresource or obtained via JavaScript which executes in the cross-origin context.

# How does User-Agent reduction affect bot detection?

Chrome's change to its user-agent string does not directly impact the user-agent string that a bot chooses to send.

Bots may choose to update their own strings to reflect the reduced information Chrome sends, but that is entirely their implementation choice. Chrome is still sending the same user-agent format, and bots that append their own identifier to the end of a Chrome user-agent string can continue to do so.

For any concerns with specific bots, it may be worth reaching out directly to the owners to ask if they have any plans to change their user-agent string.

# Engage and share feedback

• Origin trial: 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

• 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