Introduction

User-Agent Client Hints (UA-CH) are part of a Google proposal to replace the existing User-Agent HTTP header.

This page gives an overview of UA-CH detection in our API. It also provides guidance on which mechanism to use based on your use-case.

Two ways to retrieve UA-CH values

You can retrieve UA-CH values using either of these methods:

HTTP headers - Set headers in your response to ask the browser to send UA-CH values
JavaScript API - Use client-side JavaScript to retrieve UA-CH values directly

See the Guidance section below if you're unsure which to use.

This topic has the following subpages:

Headers - How to use UA-CH HTTP headers with our API.
JavaScript - How to use the UA-CH JavaScript API with our API.
Required Values - Which UA-CH values do I need?

Examples

We have examples that demonstrate UA-CH detection in various scenarios:

On-premise console
On-premise web page
Cloud console
Cloud web page
Our Configurator site includes an example for implementing a full client-side solution

Note: Console examples work in any situation. Web examples require a browser that supports UA-CH (Chrome, Edge, or other Chromium-based browsers).

Support for detection from Client Hints #

Current support

The 51Degrees Device Detection API provides comprehensive UA-CH support:

Basic support - We detect devices using the Sec-CH-UA header (since December 7, 2020)
Full support - We detect devices, operating systems, and browsers from UA-CH headers (Version 4.4 and data files from June 2022 onwards)
Windows 11 detection - We identify Windows 11 using User-Agent Client Hints (the only reliable method)

JavaScript API support

We added support for the UA-CH JavaScript API in:

.NET API version 4.4.19
Data files from March 6, 2023

Guidance #

UA-CH offers several mechanisms for accessing values. This section explains our recommendations for different use-cases.

On-premise API serving end-users directly

Using our web integration:

Ensure these properties are included: SetHeaderBrowserAccept-CH, SetHeaderHardwareAccept-CH, and SetHeaderPlatformAccept-CH
All properties are included by default for On-premise
Our software automatically sets the Accept-CH header to request needed client hints

Not using our web integration:

See the 'non-integrated' section on the UA-CH Headers page

On-premise API not serving end-users directly

Recommended approach:

Ask your clients to set the Delegate-CH meta http-equiv tag
Or have them set Permissions-Policy and Accept-CH response headers
This lets user browsers send UA-CH values to your service
See the 'B2B service supplier' section on the UA-CH Headers page

Alternative/backup approach:

Use the UA-CH JavaScript API to retrieve values
See the 'non-integrated' section on the UA-CH JavaScript page

Calling Cloud Service from client-side code

Best performance:

Set Delegate-CH meta http-equiv tag or Permissions-Policy and Accept-CH response headers
See the 'Cloud' section on the UA-CH Headers page

Alternative approach:

Ensure your Resource Key includes the JavascriptGetHighEntropyValues property
This gathers values automatically and sends them to our Cloud Service

Background reading #

How UA-CH works

The authors of the proposal have created an article covering how UA-CH works.

51Degrees has blogged extensively on the subject. We also have:

An explainer site
A test page that shows how UA-CH headers interact with Accept-CH and Permissions-Policy response headers

Google's rollout timeline

May 2021: Google outlined their UA-CH rollout plans. They confirmed that User-Agent deprecation wouldn't happen until at least 2022.

September 2021: Google provided further detail about the phased User-Agent deprecation:

Start: Chrome 101 (roughly Q2 2022)
End: Chrome 113 (roughly Q2 2023)

Technical context

User-Agent Client Hints extends the previously existing Client Hints content negotiation feature.

General documentation:

Browser support:

Additional resources

On September 28, 2022, we hosted a webinar discussing User-Agent Client Hints and the future of the User-Agent. Watch the webinar recording here.

51Degrees API Documentation 4.5

UA-CH Overview