Client Hints (User Agent deprecation) – Piano Support

In the moving context of web standards, this article will review device detection of your end-users and technical means to retrieve 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, shares it with its device detection partner to translate it, so we can give back to you precise information on the devices used by the 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 nowadays browsers are progressively deprecating the User Agent.

Chromium browsers (Chrome, Edge, Brave, Opera, Chrome Android, ...) are leading the way in this process. User Agent depreciation has already started, and will progress in 2023.

In short, we will continue to process user agents, but on some browsers this information will become less accurate until it eventually disappears.

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 with 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 require a specific request to be used, to get a better end-user data management.

Client Hints categories

Client Hints are divided in two 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 should be requested either by JS or the server.

Migrate to Client Hints

When to migrate?

On 28 February 2023, we will update our device detection system, using our device detection partner's latest API, taking Client Hints into account.

Low-entropy Client Hints

There is nothing to do here!

Low-entropy Client Hints are accessible and sent by default.

As mentioned earlier, Clients Hints will be taken into account after the service is updated on 28 February 2023.

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

High-entropy Client Hints

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

Using PA SDK

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

In other words, if you already migrated to / use our new SDKs there is no effort needed on your side!

Using your server configuration

You can configure your server so the requests sent to some 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.