Request and Implement User-Agent Client Hints

Introduction

ScientiaMobile has been following the evolution of User-Agent Client-Hints closely and we have already written a few articles that talk about the plans for User-Agent Client-Hints and support for them in the WURFL API. ImageEngine has a section dedicated to enabling Client Hint support. Google has a few developer resources that talk about this as well.

In the conversations we have had with our customers and partners over the past two years regarding User-Agent Client-Hints, one question kept popping up - how do I as a website owner start receiving User-Agent Client-Hints and what is the best way to pass this information to WURFL?

Low entropy and high entropy User-Agent Client-Hints

User-Agent Client-Hints can be broadly divided into two tiers - those that are sent with every request (Low Entropy Client Hints) and those that must specifically be requested by the server (High Entropy Client Hints). Below is a table of all the User-Agent Client-Hints (at the time of writing) and how they are sent.

User-Agent Client-Hint Low/High Entropy
sec-ch-ua Low Entropy
sec-ch-ua-mobile Low Entropy
sec-ch-ua-platform Low Entropy
sec-ch-ua-platform-version High Entropy
sec-ch-ua-full-version (deprecated) High Entropy
sec-ch-ua-full-version-list High Entropy
sec-ch-ua-model High Entropy
sec-ch-ua-arch High Entropy
sec-ch-ua-bitness High Entropy
sec-ch-ua-wow64 High Entropy

Opt in to receive User-Agent Client-Hints

Your server’s response headers must specifically advertise support for User-Agent Client-Hints using the Accept-CH response header. This response header must contain *all* high entropy User-Agent Client-Hints that you need. Here is an example Accept-CH header:

Accept-CH: sec-ch-ua-platform-version,sec-ch-ua-full-version,sec-ch-ua-full-version-list,sec-ch-ua-model,sec-ch-ua-arch,sec-ch-ua-bitness,sec-ch-ua-wow64

Alternatively, you can use the “http-equiv” meta attribute in your HTML:

<meta http-equiv="Accept-CH" content="sec-ch-ua-platform-version,sec-ch-ua-full-version,sec-ch-ua-full-version-list,sec-ch-ua-model,sec-ch-ua-arch,sec-ch-ua-bitness,sec-ch-ua-wow64" />

Get User-Agent Client-Hints quicker (optional)

When your server advertises support for User-Agent Client-Hints using the Accept-CH response header, the client device will only start sending the High Entropy User-Agent Client-Hints with the second request. This means that the very first request that the client sends will not have all the information you need and that you will need to somehow link the data from the first and second requests together to avoid duplicating visitor data.

This need for a second request can somewhat be mitigated by using one of two mechanisms: the Critical-CH response header and Application-Layer Protocol Settings (ALPS). Here is an example Critical-CH header:

Critical-CH: sec-ch-ua-platform-version,sec-ch-ua-full-version,sec-ch-ua-full-version-list,sec-ch-ua-model,sec-ch-ua-arch,sec-ch-ua-bitness,sec-ch-ua-wow64

Delegate access to the User-Agent Client-Hints data using a permissions policy (for WURFL.js and ImageEngine customers)

Now that you have requested the client to send User-Agent Client-Hints, you will need to share that data with us so that device detection can be performed. Permissions policy (formerly called feature policy) is a mechanism where you give third party websites selective access to browser data. The permissions policy is a structured header with the values containing the browser data and the websites that have access to this data. For example, to share User-Agent Client-Hints data with WURFL.js Lite, you would implement this permissions policy:

permissions-policy: ch-ua-platform-version=("https://wurfl.io"),ch-ua-full-version=("https://wurfl.io"),ch-ua-full-version-list=("https://wurfl.io"),ch-ua-model=("https://wurfl.io"),ch-ua-arch=("https://wurfl.io"),ch-ua-bitness=("https://wurfl.io"),ch-ua-wow64=("https://wurfl.io")

WURFL.js Basic, Standard and Pro customers should delegate access to “https://wjs.wurflcloud.com” instead. ImageEngine customers should refer to this document for more information.

User-Agent Reduction Deprecation Origin Trial

There is a proposal to create an origin trial for websites who require additional time to migrate to utilizing User-Agent Client-Hints. This origin trial will allow websites to access the non-reduced form of the User-Agent via the standard User-Agent header field. Signing up for this origin trial will provide a token that the website will need to include with its response. In addition to the token, the website will need to advertise support for the Sec-CH-UA-Full header using the Accept-CH mechanism or using the “http-equiv” meta attribute as demonstrated below.

Accept-CH: sec-ch-ua-full

or

<meta http-equiv="Accept-CH" content="sec-ch-ua-full" />

In addition, the website may also choose to send send a Critical-CH response header or use ALPS to get the non-reduced User-Agent string with the initial request. Here is an example Critical-CH header.

Critical-CH: sec-ch-ua-full

WURFL.js and ImageEngine customers should make sure to additionally delegate access for the Sec-CH-UA-Full header to us, using permissions policy. Here's an example permissions policy for WURFL.js Lite:

permissions-policy: ch-ua-platform-version=("https://wurfl.io"),ch-ua-full-version=("https://wurfl.io"),ch-ua-full-version-list=("https://wurfl.io"),ch-ua-model=("https://wurfl.io"),ch-ua-arch=("https://wurfl.io"),ch-ua-bitness=("https://wurfl.io"),ch-ua-wow64=("https://wurfl.io"),ch-ua-full=("https://wurfl.io")

Please note that this origin trial is a proposal and the specific client hints and mechanisms may change prior to implementation. The evolution of this proposal may be monitored here.

What User-Agent Client-Hints does WURFL need?

WURFL has always utilized all information available to it, whether from a User-Agent string or from an HTTP request. WURFL can utilize all HTTP header fields to provide the most accurate device detection possible. In fact, this is what puts us in a unique position of being able to track and adapt to changes in the User-Agent Client-Hints specification so quickly. For best detection results, we recommend that you pass the entire intact HTTP header with the following User-Agent Client-Hints to WURFL:

sec-ch-ua,sec-ch-ua-mobile,sec-ch-ua-platform,sec-ch-ua-platform-version,sec-ch-ua-full-version,sec-ch-ua-full-version-list,sec-ch-ua-model,sec-ch-ua-arch,sec-ch-ua-bitness,sec-ch-ua-wow64

As the User-Agent Client-Hints evolve, we will update our recommendation to include all the hints needed for an accurate device detection.