Required UA-CH headers

Overview🔗

This page explains which User-Agent Client Hints (UA-CH) values you need in order to get results for different properties.

If you just want to get all properties, you'll need the following UA-CH values. We generally recommend supplying all of these for the best detection results:

• Sec-CH-UA
• Sec-CH-UA-Full-Version-List
• Sec-CH-UA-Model
• Sec-CH-UA-Mobile
• Sec-CH-UA-Platform
• Sec-CH-UA-Platform-Version

To request only the values needed for specific properties, use the component table below.

Background🔗

51Degrees groups properties associated with the request by ‘component’. The components 51Degrees recognize are hardware device, platform (operating system), browser, and crawler.

The User-Agent header contains information relating to all four of these components. User-Agent Client Hints values are different in that they relate to varying numbers of components. For example, the Sec-CH-UA-Model header only relates to the hardware device component.

However, multiple UA-CH values are sometimes needed to fully identify a component. For example, Chrome on a Mac will not populate the Sec-CH-UA-Model header, so that won't help give us an answer to the hardware component. Instead, we need the Sec-CH-UA-Platform header, which can at least tell us that this is a macOS device.

We concatenate the various UA-CH headers that are needed to identify a component to create ‘pseudo-headers’. These are then used internally to perform the detection.

Pseudo-headers🔗

The table shows the UA-CH values used to build pseudo-headers for each component. We recommend providing all UA-CH values for the best detection results. This applies to Chromium-based browsers. Continue supplying User-Agent information for other browsers.

Some pseudo-headers are not required to detect the component but can provide more detailed detection results. For example, Sec-CH-UA-Platform-Version is not required to determine the Platform component, but provides additional version information when supplied.

In some cases, there are multiple pseudo-headers for a component. These are processed in order from providing most detail to least. In addition, a pseudo-header within the length limit below will take precedence over the User-Agent, even in cases where the User-Agent provides more detail.

Pseudo-headers are built in working memory of a fixed size, so a pseudo-header longer than the limit is ignored. A single header such as User-Agent has the same limit and is ignored in the same way, including when it is passed directly rather than as evidence. No error is reported and detection moves on to the next header, which can mean the result rests on less detailed evidence. If no other header is usable the results hold no match. The limit is 500 bytes by default and counts one separator between each value of a pseudo-header.

To raise the limit, set a larger value before creating the engine, which uses more memory for each set of results. The setting is maxMatchedUserAgentLength in C and Node.js, setMaxMatchedUserAgentLength in C++, and max_matched_useragent_length in Python and PHP. The .NET and Java pipeline builders do not offer this setting.

Key🔗

• x = This value is required in order to determine the component.
• x* = This value is not required, but if provided may return more detailed results.
• y and z = One of these values is required. Supplying y may return a more accurate result and removes the need to supply z.