User agent client hints

Overview overview

Every time a web browser makes a request to a web server, the header of the request includes information about the browser and the environment on which the browser is running. All this data is aggregated into a string, called the user agent string.

Here is an example of what a user agent string looks like on a request coming from a Chrome browser running on a Mac OS device.

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36`

Use cases use-cases

User agent strings have long been used to provide marketing and development teams with important insights into how browsers, operating systems and devices display site content, as well as how users interact with websites.

User agent strings are also used to block spam and filter bots that crawl sites for a variety of additional purposes.

User agent strings in Adobe Experience Cloud user-agent-in-adobe

Adobe Experience Cloud solutions utilize the user agent strings in various ways.

Introducing user agent client hints ua-ch

In recent years, site owners and marketing vendors have used user agent strings along with other information included in request headers to create digital fingerprints. These fingerprints can be used as a means of identifying users without their knowledge.

Despite the important purpose that user agent strings serve for site owners, browser developers have decided to change how user agent strings operate, to limit potential privacy issues for end-users.

The solution they developed is called user agent client hints. Client hints still allow websites to collect necessary browser, operating system and device information, while also providing increased protection against covert tracking methods, such as fingerprinting.

Client hints allow website owners to access much of the same information available in the user agent string, but in a more privacy-preserving way.

When modern browsers send a user to a web server, the entire user agent string is sent on every request, regardless of whether it is required. Client hints, on the other hand, enforce a model where the server must ask the browser for the additional information it wants to know about the client. Upon receiving this request, the browser can apply its own policies or user configuration to determine what data is returned. Instead of exposing the entire user agent string by default on all requests, access is now managed in an explicit and auditable way.

Browser support browser-support

User agent client hints were introduced with Google Chrome version 89.

Additional Chromium-based browsers support the Client Hints API, such as:

Categories categories

There are two categories of user agent client hints:

Low entropy client hints low-entropy

Low entropy client hints include basic information which cannot be used to fingerprint users. Information such as browser brand, platform, and whether the request is coming from a mobile device.

Low entropy client hints are enabled by default in Web SDK, and are passed on every request.

High entropy client hints high-entropy

High entropy client hints are more detailed information about the client device, such as platform version, architecture, model, bitness (64 bit or 32 bit platforms), or full operating system version. This information could potentially be used in fingerprinting.

High entropy client hints are disabled by default in Web SDK. To enable them you must manually configure the Web SDK to request high entropy client hints.

High entropy client hints impact on Experience Cloud solutions impact-in-experience-cloud-solutions

Some Adobe Experience Cloud solutions rely on information included in high entropy client hints when generating reports.

If you do not enable high entropy client hints in your environment, the Adobe Analytics and Audience Manager reports and traits described below will not work.

Adobe Analytics reports relying on high entropy client hints analytics

The Operating system dimension includes opertating system version which is stored as a high entropy client hint. If high entropy clients hints is not enabled, operating system version may be inaccurate for hits collected from Chromium browsers.

Audience Manager traits relying on high entropy client hints aam

Google has updated the Chrome browser functionality to minimize the information collected via the User-Agent header. As a result, Audience Manager customers using DIL will no longer receive reliable information for traits based on platform-level keys.

Audience Manager customers who use platform-level keys for targeting must switch to Experience Platform Web SDK instead of DIL, and enable High Entropy Client Hints to continue receiving reliable trait data.

Enabling high entropy client hints enabling-high-entropy-client-hints

To enable high entropy client hints on your Web SDK deployment, you must include the additional highEntropyUserAgentHints context option in the context field.

For example, to retrieve high entropy client hints from web properties, your configuration would look like this:

context: ["highEntropyUserAgentHints", "web"]

Example example

Client hints contained in the headers of the first request made by the browser to a web server will contain the browser brand, the major version of the browser, and an indicator of whether the client is a mobile device. Each piece of data will have its own header value rather than being grouped into a single user agent string, as shown below:

Sec-CH-UA: "Chromium";v="101", "Google Chrome";v="101", " Not;A Brand";v="99"

Sec-CH-UA-Mobile: ?0

Sec-CH-UA-Platform: "macOS

The equivalent User-Agent header for the same browser would look like this:

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36

While the information is similar, the first request to the server contains client hints. These only include a subset of what is available in the user agent string. Missing from the request is the operating system architecture, full operating system version, layout engine name, layout engine version, and the full browser version.

However, on subsequent requests, the Client Hints API allows web servers to ask for additional details about the device. When these values are requested, depending on browser policy or user settings, the browser response may include that information.

Below is an example of the JSON object that is returned by the Client Hints API when high entropy values are requested:

{
   "architecture":"x86",
   "bitness":"64",
   "brands":[
      {
         "brand":" Not A;Brand",
         "version":"99"
      },
      {
         "brand":"Chromium",
         "version":"100"
      },
      {
         "brand":"Google Chrome",
         "version":"100"
      }
   ],
   "fullVersionList":[
      {
         "brand":" Not A;Brand",
         "version":"99.0.0.0"
      },
      {
         "brand":"Chromium",
         "version":"100.0.4896.127"
      },
      {
         "brand":"Google Chrome",
         "version":"100.0.4896.127"
      }
   ],
   "mobile":false,
   "model":"",
   "platformVersion":"12.2.1"
}