We’ve migrated our documentation to a new site, which means some URLs have changed. If you hit a broken link, submit a support ticket.
Analytics
Analytics
Breadcrumbs

Client Hints (User Agent deprecation)

In the moving context of web standards, this article reviews device detection of your end-users and the technical means used to retrieve device information.

User Agents

Historically, detection of technical information (OS, browser, mobile device model, ...) is based on the User Agent, a string communicated by the browser via the header of HTTP requests:

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

Piano Analytics retrieves this string and shares it with its device detection partner to translate it, so we can give you back precise information on the devices used by your end-users.

For example, the User Agent above will be translated into:

Browser

Browser Version

Operating System

OS Version

Google Chrome

107.0.0.0

Apple OS X

10.15.7 (Catalina)

This is how it worked for years, but browsers have progressively reduced the information exposed by the User Agent.

Chromium browsers (Chrome, Edge, Brave, Opera, Chrome Android, and so on) led the way in this process. Chrome has completed its User-Agent reduction: the string is now frozen to a fixed, generic format that no longer exposes the browser minor version, the OS version, or the device model. On mobile, for instance, Chrome reports a generic Android 10; K regardless of the actual device.

In short, we still process User Agents, but on Chromium browsers this string has become far less precise. It has not disappeared — it has been reduced — so a more reliable alternative is needed for detailed device detection.

The alternative to the User Agent already exists: Client Hints.

Client Hints

Client Hints are the new norm for Chromium browsers regarding device detection. They contain the same information as the User Agent before its deprecation, with two advantages.

Advantages

A new format

Device information in Client Hints comes in a new format, much more readable and easier to handle than User Agents:

sec-ch-ua: "Google Chrome";v="107", "Chromium";v="107", "Not=A?Brand";v="24"
sec-ch-ua-mobile: ?0
sec-ch-ua-platform: "macOS"

These Client Hints give the same info as the User Agent in the previous part (the OS Version excepted).

Harder access to the information

Client Hints are not all accessible by default. Some information requires a specific request to be used, allowing better end-user data management.

Client Hints categories

Client Hints are divided iintotwo categories. The two categories are not accessible in the same way and don't contain the same depth of information.

Low-entropy Hints

Low-entropy Client Hints contain basic, but really useful, information.

This is what you can see in the "A new format" section above, and detailed below:

Browser

Browser Version

Operating System

Google Chrome

107.0.0.0

Apple OS X

They stand for the following properties in your Piano Analytics Data Model:

  • browser

  • browser_version

  • os

These properties are available by default, and are sent in every request we receive (header of the request). Just like we did with Use Agents!

High-entropy Hints

High-entropy Client Hints contain all the information you can have on an end-user device:

Sec-CH-UA: "Google Chrome";v="107", "Chromium";v="107", "Not=A?Brand";v="24"
Sec-CH-UA-Mobile: ?0
Sec-CH-UA-Full-Version: "107.0.5304.62"
Sec-CH-UA-Full-Version-List: "Google Chrome";v="107.0.5304.62", "Chromium";v="107.0.5304.62", "Not=A?Brand";v="24.0.0.0"
Sec-CH-UA-Platform: "macOS"
Sec-CH-UA-Platform-Version: "13.0.0"
Sec-CH-UA-Arch: "arm"
Sec-CH-UA-Wow64: ?0
Sec-CH-UA-Bitness: "64"

These properties are not available by default. They must be requested, either by JS or by the server.

Client Hints and device detection

Our device detection system uses our detection partner's API with support for Client Hints (rolled out on 28 February 2023). Low-entropy Client Hints are used automatically; for high-entropy Client Hints, you may need to take one of the actions described below.

Low-entropy Client Hints

There is nothing to do here!

Low-entropy Client Hints are accessible and sent by default, and are automatically taken into account by our device detection.

With no effort, you benefit from the best device detection possible.

High-entropy Client Hints

If you want complete device detection, relying on high-entropy Client Hints, you may consider these 2 options.

Using the PA SDK

Our Piano Analytics JS SDK requests and sends all the high-entropy Client Hints by default. These properties are visible through Stream Inspector or the Tag Inspector web browser add-on.

In other words, if you already use our current SDKs, there is no effort needed on your side!

 Using your server configuration

You can configure your server so that requests sent to certain domains include high-entropy Client Hints headers.

You must allow 2 headers:

  • Accept-CH

  • Permissions-Policy

We strongly suggest you to include all following Client Hints:

  • ch-ua

  • ch-ua-mobile

  • ch-ua-platform

  • ch-ua-arch

  • ch-ua-bitness

  • ch-ua-full-version-list

  • ch-ua-model

  • ch-ua-platform-version

Technical implementation:

Accept-CH: Sec-CH-UA, Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA-Arch, Sec-CH-UA-Bitness, Sec-CH-UA-Full-Version-List, Sec-CH-UA-Model, Sec-CH-UA-Platform-Version

https://developer.chrome.com/docs/privacy-sandbox/permissions-policy/

Permissions-Policy: ch-ua=("https://collectiondomain"), ch-ua-mobile=("https://collectiondomain"), ch-ua-platform=("https://collectiondomain"), ch-ua-arch=("https://collectiondomain"), ch-ua-bitness=("https://collectiondomain"), ch-ua-full-version-list=("https://collectiondomain"), ch-ua-model=("https://collectiondomain"), ch-ua-platform-version=("https://collectiondomain")

You can find your collection domain thanks to our documentation.

Using Meta Tags in the HTML page

You can use specific meta tags in your pages so the requests sent to some domains include High-Entropy Client Hints headers.

Technical implementation:

https://collectiondomain; ch-ua-bitness https://collectiondomain; ch-ua-full-version-list https://collectiondomain; ch-ua-model https://collectiondomain; ch-ua-platform-version https://collectiondomain";>

 

Label changes

With this device detection service update from User-Agent to Client Hints and User Agents, will come a few changes:

  • Chrome Mobile

    • The Chrome Mobile browser name has been changed to Chrome to be consistent with Google's naming policy.

  • macOS & iOS osVersion

    • Now converts the osVersion to have dot-notation so the example 10_5_7 becomes 10.5.7.

  • Browser Vendor & Model

    • Previously, some desktop browsers set the device vendor and model to be the browser vendor and browser name if no device was identified. After the update, the API no longer has this behaviour. Please use the browserVendor and browserName properties instead.

  • Android Browser

    • Previously, the API returned the browser name Android Browser for some app WebView and Set Top box User-Agents. The API now returns Chrome instead.

    • Previously, the API returned the browser name Android Browser for some Amazon devices running the Silk browser. The API now returns Amazon Silk instead

  • HuaweiBrowser

    • The Huawei browser naming has changed from HuaweiBrowser to Huawei Browser.

  • macOS

    • The osName for the macOS family of operating systems has been updated to better reflect the correct naming for each version of macOS. The names Mac OS X, OS X and macOS will be returned depending on what osVersion is detected.

  • Linux

    • The osVersionName for Linux distros is not currently well populated and will improve over time.

  • isApp / appName

    • The current version of the data provided with the API has limited support for isApp and appName. Subsequent releases will correct this.

  • Other Properties

    • The new API has improved support for non-standard User-Agents. Differences may be observed compared to the previous version.

Last updated: