Client-side Component

The DeviceAtlas Client-Side Component is a compact JavaScript library designed to provide additional details to the server-side DeviceAtlas SDK to assist with the recognition and characterisation of certain classes of devices and browsers. It is can be embedded in web pages as a standalone library or as part of a tag management system.

The need for a client-side component

Until recently HTTP headers alone were sufficient for DeviceAtlas to recognise and characterise most devices. This is no longer the case for two reasons:

Apple deliberately prevents iOS and iPadOS devices from being differentiated by HTTP headers alone;
Google's User-Agent Client Hints initiative moves granular device and browser data out of the User-Agent header and into a new set of HTTP headers and JavaScript APIs.

The DeviceAtlas Client-Side Component is designed to help solve these problems. It is a very compact JavaScript library designed to work on the widest possible range of devices and browsers. The library returns properties to be used with the DeviceAtlas API or consumed on the client side independent of the DeviceAtlas API. The library is self-contained and does not make any calls to external services.

Device recognition limitations without Client-Side Component

iOS and iPadOS devices

It is not possible to differentiate between certain iOS and iPadOS models due to a deliberate stance on Apple's part. Since DeviceAtlas cannot be certain which model in particular is making a request it returns the lowest common denominator device, the original 2007 iPhone. This is a conscious decision—DeviceAtlas has a policy of returning only properties that can be reliably determined. The original iPhone is the least capable iPhone and thus the safest device to default to, absent better evidence.

A similar situation applies to iPad OS devices—DeviceAtlas will not be able to differentiate between some iPad models. Also, DeviceAtlas will not be able to differentiate between macOS devices running Safari and iPad devices due to another deliberate stance on Apple's part.

User-Agent Client Hints

Since 2023 most Chromium-based browsers (Chrome, Edge, Brave, Vivaldi) on mobile and desktop have adopted User-Agent Client Hints as their means for relaying granular browser and device information to websites, leaving a frozen User-Agent string with just some basic facts.

In this situation, for DeviceAtlas to be able to do its job, it needs access to the User-Agent Client Hints made available by the browser. This can be achieved in two ways:

By configuring your web server response headers to request User-Agent Client Hints from the browser and passing the subsequent Client Hint headers to DeviceAtlas;
By obtaining User-Agent Client Hint data via JavaScript on the client. One way to achieve this is to deploy the DeviceAtlas Client-Side Component on your website. This is typically easier to achieve than changing your web server response headers.

The sequence diagram below shows how the DeviceAtlas Client-Side component fits into a page load sequence from a browser.