User-agent and Client Hints

Last update: July 17, 2023

CREATED FOR:

  • Developer

Adobe Target uses the user-agent to qualify visitors for segmentation and personalization.

NOTE
The information in this article applies to at.js version 2.9.0 (or later).

Each time a web browser makes a request to a server, information about the browser and the environment where the browser runs are included in the header of the request. Since the early days of the Internet, this data has been aggregated in a single string called the user-agent.

The following text is a sample user-agent of a Mac OS X-based computer using a Safari Browser:

Mozilla/5.0 (Linux; Android 12; SM-S908E) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.41 Mobile Safari/537.36

From this user-agent, the server receiving the request can discern the following information about the browser and operating system:

InformationDetails
Software nameChrome
Software version101
Full software version101.0.4951.41
Layout engine nameAppleWebKit
Layout engine version537.36
Operating systemAndroid
Operating system versionAndroid 12 (Snow Cone)
DeviceSM-S908E (Samsung Galaxy S22 Ultra)

Over the years, the amount of browser and device information included in the user-agent string has grown.

User-agent use cases

User-agents have long been used to provide marketing and developer teams with important insights into how browsers, operating systems, and devices display site content, as well as how users interact with websites. User-agents are also used to block spam and filter bots that crawl sites for a variety of additional purposes.

However, in recent years some site owners and marketing vendors have used the user-agent along with other information included in request headers to create digital fingerprints that can be used as a means of identifying users without their knowledge. Despite the important purpose the user-agent serves for site owners, browser developers have decided to make changes to how user-agents operate to limit potential privacy issues for site visitors.

Browser developers created User-Agent Client Hints as a solution to this challenge. Client Hints still allow sites to collect necessary browser, operating system, and device information, while also providing increased protection against covert tracking methods, such as fingerprinting.

Client Hints

User-Agent Client Hints provide website owners the ability to access much of the same information available in the user-agent, but in a more privacy-preserving way. When modern browsers send a user-agent to a web server, the entire user-agent 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 by default on all requests, access is now managed in an explicit and auditable fashion.

User-Agent Client Hints have been available in Chrome since version 89. Recent versions of Chromium-based browsers, such as Microsoft Edge, Opera, Brave, Chrome Android, Opera Android, and Samsung Internet, also support the Client Hints API.

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

For example, here are some Client Hints:

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"

…whereas this is the user-agent for the same browser:

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

Although the information is similar, the first request to the server contains Client Hints that contain only a subset of what is available in the user-agent string. Missing from the request is the OS architecture, full OS version, layout engine name, layout engine version, and the full browser version. However, on subsequent requests, the Client Hints API does allow for web servers to ask for additional, high entropy details about the device. When these high entropy values are requested, depending on browser policy or user settings, the browser response can include that information.

The following example is a 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"
}

The high entropy values include several additional pieces of information that are not available in the default Client Hints information. The following table contains details of what data is available in the default request vs. the high entropy User-Agent Client Hints information.

HTTP headerJavaScriptUser-agentClient hintHigh entropy client hint
Sec-CH-UAbrandsYesYesNo
Sec-CH-UA-PlatformplatformYesYesNo
Sec-CH-UA-MobilemobileYesYesNo
Sec-CH-UA-Platform-VersionplatformVersionYesNoYes
Sec-CH-UA-ArcharchitectureYesNoYes
Sec-CH-UA-ModelmodelYesNoYes
Sec-CH-UA-BitnessBitnessYesNoYes
Sec-CH-UA-Full-Version-ListfullVersionListYesNoYes

Migration to Client Hints

Currently, Chromium-based browsers continue to send the user-agent along with Client Hints in the headers of requests made to web servers. However, starting in April 2022 and continuing through February 2023, the amount of data contained in the user-agent string will be reduced. Other browsers, such as Safari and Firefox, will continue to leverage the user-agent string; however, they too will be reducing the amount of information contained therein.

Target use cases that require Client Hints

The following use cases in Target require Client Hints:

Audience attributes

If you use Target audiences and use any of the following audience attributes, Target requires Client Hints to perform the correct segmentation:

  • Browser
  • Operating System
  • Mobile

Profile scripts

If you use profile scripts and reference the user.browser attribute (which refers to user-agent), you might need to update the profile script to also check one or more Client Hints. You can access any of the Client Hints using the function user.clientHint('sec-ch-ua-xxxxx'). The Client Hint header name must be all lower-case.

The following example shows how to properly detect a Windows OS in a profile script:

"return (((user.browser != null) && (user.browser.indexOf(\"Windows\") > -1)) || " +
      "((user.clientHint('sec-ch-ua-platform') != null) &&
(user.clientHint('sec-ch-ua-platform') === 'Windows')));"

Here is a table of Client Hints and their corresponding profile script usage semantics.

Client Hint headerEntropyAudience AttributeProfile Script Usage
Sec-CH-UALowBrowseruser.clientHint('sec-ch-ua')
Sec-CH-UA-ArchHighExposed to users via profile scriptsuser.clientHint('sec-ch-ua-arch')
Sec-CH-UA-BitnessHighExposed to users via profile scriptsuser.clientHint('sec-ch-ua-bitness')
Sec-CH-UA-Full-Version-ListHighBrowseruser.clientHint('sec-ch-ua-full-version-list')
Sec-CH-UA-MobileLowMobileuser.clientHint('sec-ch-ua-mobile')
Sec-CH-UA-ModelHighMobileuser.clientHint('sec-ch-ua-model')
Sec-CH-UA-PlatformLowOperating systemuser.clientHint('sec-ch-ua-platform')
Sec-CH-UA-Platform-VersionHighExposed to users via profile scriptsuser.clientHint('sec-ch-ua-platform-version')

How to pass Client Hints to Adobe Target

The following sections contain more information about how to pass Client Hints, depending on your Target implementation.

at.js version 2.9.0 (or later)

Starting with at.js 2.9.0, User Agent Client Hints will be collected automatically from the browser and sent to Target when getOffer/getOffers() is called. By default, at.js collects only “Low Entropy” Client Hints. If performing audience segmentation or using profile scripts based on data categorized as “High Entropy” from the preceding sections, you need to configure at.js to collect “High Entropy” Client Hints from the browser via targetGlobalSettings.

window.targetGlobalSettings = { allowHighEntropyClientHints: true };

Server-side SDKs

For more information on how to pass Client Hints via server-side SDKs, see Client Hints under Server-side Implementation documentation.

Previous pageat.js cookies
Next pageUnderstand the global mbox overview

Target


Personalization & Experiementation Excellence with Recommendations and AI

Adobe Customer Success Webinars

Tuesday, Mar 4, 4:00 PM UTC

Adobe Target innovations, including GenAI, and best practices on AI-powered personalization and experimentation at scale.

Register

Connect with Experience League at Summit!

Get front-row access to top sessions, hands-on activities, and networking—wherever you are!

Learn more

Register now