Client Hints (User Agent deprecation)

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:

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:

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.

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.