The best method for you will depend on your business
As part of the roll-out of the User-Agent reduction in Chromium browsers, Google is encouraging developers who wish to access detailed device data to use the User-Agent Client Hints API.
User-Agent Client Hints (UA-CH) are Google’s own HTTP request header, and there are various methods businesses can use to implement UA-CH data. However, there is not a one-size-fits-all method.
We kindly urge the people reading this who assume this isn’t relevant to pass this blog to a member of their engineering, product, or website team, as this implementation may be of interest to them.
We’ve identified three methods that businesses can use to implement UA-CH data.
First, you need to assess whether your business and your products have control, can access, or own the domain for which you want to request UA-CH data. For example, certain B2B businesss have their software set up in such a way that this part of the process is actually owned by their customers within a client-side integration. These businesses would not have any ownership or control over the first nor third-party domain.
Once you have assessed your ownership of the domains, follow the below flowchart to see which method you should use to implement UA-CH.
Jump to:
Delegate-CH or Permissions-Policy
Bonus: use the 51Degrees cloud service or 51Degrees UAParser
Accept-CH
Accept-CH is the easiest method to use, but only if the business has control over the first-party domain.
By default, Chromium browsers will send three User-Agent Client Hints headers: Sec-CH-UA, Sec-CH-UA-Mobile, and Sec-CH-UA-Platform – these are known as low entropy hints.
If additional UA-CH headers (high entropy hints) are required, then the server must request them by sending an Accept-CH header to the browser. The browser then sends these additional UA-CH headers to any URL of the first-party domain in subsequent requests.
What UA-CH you require will dictate how your Accept-CH header may be configured. For example, your Accept-CH header may look like this if you require a lot of data:
Accept-CH: Sec-CH-UA, Sec-CH-UA-Arch, Sec-CH-UA-Bitness, Sec-CH-UA-Full-Version, Sec-CH-UA-Full-Version-List, Sec-CH-UA-Mobile, Sec-CH-UA-Model, Sec-CH-UA-Platform, Sec-CH-UA-Platform-Version, Sec-CH-UA-WoW64
You may also need to use the Vary HTTP header with the same field names as the Accept-CH header. This is required so the server can indicate which Client Hints affect the selected response and whether the selected response is appropriate for a later request. For example:
Accept-CH: Sec-CH-UA, Sec-CH-UA-Full-Version, Sec-CH-UA-Full-Version-List
Vary: Sec-CH-UA, Sec-CH-UA-Full-Version, Sec-CH-UA-Full-Version-List
The Accept-CH method only works if the headers are sent to the first-party domain. It does not send the additional UA-CH headers to the third-party domain. For that, you need a different method: Delegate-CH or Permissions-Policy.
Delegate-CH or Permissions-Policy
This method is appropriate if you do not control the first-party domain, for example, if you are a B2B business who only controls the third-party domain.
To send the non-default, high entropy hints to the third-party domain, the first-party server must specify that it’s okay to send the UA-CH headers by using either:
- HTML: Delegate-CH
- HTTP response headers: Permissions-Policy (used alongside the Accept-CH header)
Delegate-CH allows for delegation of high entropy hints in a single meta tag and it tells the browser that it should include the specified Client Hints headers when it makes requests to that domain.
The implementation is simple as it only requires a change to the HTML. Simply add the Delegate-CH meta tag in the head of the page. For 51Degrees cloud users, this would look like this:
<head>
<meta http-equiv="Delegate-CH" content="sec-ch-ua-full-version-list https://cloud.51degrees.com; sec-ch-ua-model https://cloud.51degrees.com; sec-ch-ua-platform https://cloud.51degrees.com; sec-ch-ua-platform-version https://cloud.51degrees.com"/>
</head>
A Permissions Policy is a feature that gives third-party domains selective access to browser data, enabling cross-origin User-Agent Client Hints delegation. The Permissions-Policy header will do the same job as Delegate-CH but uses HTTP response headers rather than HTML.
The browser will only send the UA-CH headers to the third-party that are also requested by the first-party server, so the Accept-CH header must also request the UA-CH headers.
As an example, the Permissions-Policy header may look like this:
Accept-CH: Sec-CH-UA-Platform-Version, DPR
Permissions-Policy: ch-ua-platform-version=(self "downloads.example.com"),
ch-dpr=(self "cdn.provider" "img.example.com");
getHighEntropyValues
This final method is perfect for B2B businesses as they do not need to rely on the individual nor add the Delegate-CH or Permissions-Policy.
You can use JavaScript to get the high entropy hints (the call is aptly named getHighEntropyValues); you pass the values you want, and it returns a promise with an object containing the specific values.
We’ve created a new 51Degrees property, JavascriptGetHighEntropyValues, for our customers to easily implement UA-CH data in their environment. Follow our JavaScript User-Agent Client Hints documentation which details the JavaScript approach with our API.
Learn more about implementing JavascriptGetHighEntropyValuesWe also have documentation on converting User-Agent Client Hints obtained through the getHighEntropyValues() browser API into HTTP headers format.
Bonus: use the 51Degrees cloud service or 51Degrees UAParser
Alternative methods do exist for businesses who are not limited to on-premise implementations.
The 51Degrees cloud service can be used to gather User-Agent Client Hints information. Or you could use the open source 51Degrees UAParser, which builds upon the UAparser.js package. Both have full User-Agent Client Hints support.
Conclusion
Google has made implementing User-Agent Client Hints complicated, but we provide the necessary tools to make it simple.
For more information, follow our improved User-Agent Client Hints documentation. If you experience any issues regarding implementing UA-CH data within 51Degrees services, please do contact us.