Guide
TrainingSupportCommunity

Support for user agent reduction and client hints

Suggest Edits

mPulse Support for user agent reduction and client hints

Chrome is making changes to the browser’s User-Agent header that will affect how web servers, applications, CDNs, and products like mPulse gather information about the user agent (such as the browser’s version, platform and device information).

Some changes to the User-Agent header, such as reduced browser version information, are already in effect. Additional changes will begin rolling out on October 25, 2022 with Chrome 107. At that time, the Desktop platform will be frozen. In February 2023, Chrome 110 will freeze the Mobile platform.

To complement the reduction and freezing of the User-Agent string, there is a browser feature that websites can use called User-Agent Client Hints, which is a request-based mechanism to gather the same information being removed from the User-Agent header. The difference is that client hints need to be explicitly requested (in the HTTP response), and the browser can then optionally include those extra "hints" on future HTTP requests.

How mPulse uses the User-Agent and Client Hint headers

mPulse utilizes the User-Agent header to help classify visitors. It is used to fill in the following dimensions:

  • Browser
  • Browser Family
  • OS
  • OS Family
  • Device Manufacturer
  • Device Model
  • Device Type

To support the User-Agent reduction from Chrome, mPulse has added support for Client Hints to gather the same information.

In order to retain the same detail of information after these Chrome changes are in effect, mPulse customers will need to request Client Hints for their HTML pages, and delegate those hints to mPulse. See below for details on how to request Client Hints.

Changes with the User-Agent header reduction

If you take a recent Chrome User-Agent HTTP header (Chrome 100 on a Samsung Android device):

Mozilla/5.0 (Linux; Android 11; SM-G975U) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36

There are several tokens in the above header that will be reduced or frozen:

  • The Chrome version will only contain the major version: 100.0.4896.127 to 100.0.0.0
  • The Android platform will be locked to Android 10: Android 11 to Android 10 (even for Android 1-9 and 11+)
  • The mobile device name will be removed and replaced with "K": SM-G975U to K

As a result, the reduced User-Agent header will soon look like this:

Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.0.0 Mobile Safari/537.36

Without the support of Client Hints, this newly reduced User-Agent header would be incorrectly interpreted as an Android 10 device without a device name.

More details on the frozen platforms are available at https://www.chromium.org/updates/ua-reduction/

How to use client hints

Client Hints are new browser feature where websites can request the browser send the same information that has been removed from the User-Agent header.

Some client hints will come by default:

  • Sec-CH-UA
  • Sec-CH-UA-Mobile
  • Sec-CH-UA-Platform

However, all other client hints will need to be requested through the Accept-CH response header. The browser may then send the additional hints to subdomains and on subsequent requests.

Here's how client hints may look in a typical HTTP workflow.

  1. On the first visit, the browser will send its request for the page, the reduced User-Agent header, and the default client hints:

    GET / HTTP/1.1
...
User-Agent: Mozilla/5.0 (Linux; Android 11; SM-G975U) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36
Sec-CH-UA: "Google Chrome";v="100", " Not;A Brand";v="100", "Chromium";v="100"
Sec-CH-UA-Mobile: ?1
Sec-CH-UA-Platform: "Android"
...

  2. The server's response may request additional client hints (and delegate some of those hints to sub-resource domains, via the Permissions-Policy header):

    ...
Accept-CH: Sec-CH-UA-Model, Sec-CH-UA-Platform-Version
Permissions-Policy: ch-ua-model=("*" self), ch-ua-platform-version=("*" self)
...

  3. Then, for sub-resource requests and future navigations, the browser may send additional hints:

    GET /page2 HTTP/1.1
...
User-Agent: Mozilla/5.0 (Linux; Android 11; SM-G975U) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36
Sec-CH-UA: "Google Chrome";v="100", " Not;A Brand";v="100", "Chromium";v="100"
Sec-CH-UA-Mobile: ?1
Sec-CH-UA-Platform: "Android"
Sec-CH-UA-Full-Version: "100.0.4896.127"
Sec-CH-UA-Platform-Version: 12
Sec-CH-UA-Model: SM-G975U
...

By using the combination of the reduced User-Agent header and new client hints, services like mPulse can report on the same dimensions as before.

Requesting client hints for mPulse

In order to ensure mPulse can continue to report correct information for the Browser, Operating System and Device dimensions, two client hints should be requested.

Specifically, the Sec-CH-UA-Model and Sec-CH-UA-Platform-Version hints will ensure mPulse has access to all of the information it had before.

These hints will need to be delegated to the *.akstat.io and *.go-mpulse.net domains that mPulse communicates with. Since client hints cannot be currently delegated to wildcard subdomains, delegating those hints to all domains (*) is necessary.

There are two methods for requesting these client hints for mPulse:

Method 1: Gathering Client Hints from boomerang.js

Boomerang version 1.766 and onward has the ability to requet Client Hints in JavaScript, and to include this information on the mPulse beacon.

To enable the collection of Client Hints, you can turn on the request_client_hints option.

In JavaScript:

window.BOOMR_config = window.BOOMR_config || {};
window.BOOMR_config.request_client_hints = true;

In Property Manager in the mPulse Additional Options JSON:

{ "request_client_hints": true }

Method 2: Add client hint requests from the origin

The origin web server can be modified to emit the addtional Accept-CH and Permissions-Policy headers.

These are the headers you will need to add to all HTML pages:

Accept-CH: Sec-CH-UA-Model, Sec-CH-UA-Platform-Version
Permissions-Policy: ch-ua-model=("*" self), ch-ua-platform-version=("*" self)

If you are already sending Accept-CH or Permissions-Policy, the above clauses will need to be merged into those headers.

These headers do not need to be included on any sub-resources -- just HTML content.

Questions?

If you have any questions, please contact your support team for details.

Updated over 1 year ago