The best method for you will depend on your business
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.
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:
<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"/>
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:
Learn more about implementing Delegate-CH or Permissions-Policy
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");
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.
We 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.
Google has made implementing User-Agent Client Hints complicated, but we provide the necessary tools to make it simple.