Skip to main content

user-agent

A set of methods for parsing userAgent and getting browser data. Library for parsing and executing checks by:

parseClientHintsHeaders​

Used on the server to supplement information from ClientHints headers (sec-ch-ua). The parseClientHintsUserAgentData method constructs an object with information based on the headers, enriches it with browser details, fills in additional fields, and ensures backward compatibility in naming. Essentially, it performs data preparation and some data hygiene. For example, when parsing headers with low entropy,

const headers = {
  'sec-ch-ua': '"Chromium";v="106", "Google Chrome";v="106", "Not;A=Brand";v="99"',
  'sec-ch-ua-mobile': '?0',
  'sec-ch-ua-platform': '"Windows"',
};

We get

const userAgent = {
  browser: {
    browserEngine: 'chrome',
    major: '106',
    name: 'chrome',
    version: '106',
  },
  cpu: {
    architecture: undefined,
  },
  device: {
    model: undefined,
    type: 'desktop',
    vendor: undefined,
  },
  engine: {
    name: 'Blink',
    version: '106',
  },
  mobileOS: undefined,
  os: {
    name: 'Windows',
    version: undefined,
  },
  sameSiteNoneCompatible: true,
};

When parsing headers with high entropy,

const headers = {
  'sec-ch-ua-full-version-list':
    '"Not.A/Brand";v="8.0.0.0", "Chromium";v="110.0.5481.100", "Google Chrome";v="110.0.5481.100"',
  'sec-ch-ua-platform-version': '"10.0.19044.2364"',
  'sec-ch-ua-arch': '"x86_64"',
  'sec-ch-ua-model': '"iPhone 13"',
};

We get

const userAgent = {
  browser: {
    browserEngine: 'chrome',
    major: '110.0.5481.100',
    name: 'chrome',
    version: '110.0.5481.100',
  },
  cpu: {
    architecture: 'x86_64',
  },
  device: {
    model: 'iPhone 13',
    type: 'desktop',
    vendor: undefined,
  },
  engine: {
    name: 'Blink',
    version: '110.0.5481.100',
  },
  mobileOS: undefined,
  os: {
    name: undefined,
    version: '10.0.19044.2364',
  },
  sameSiteNoneCompatible: true,
};

parseClientHintsUserAgentData​

Used on the client to supplement information from navigator.userAgentData.

The parseClientHintsUserAgentData method enriches the object with browser information, fills in additional fields, and ensures backward compatibility in naming. Essentially, it performs data preparation and some data hygiene.

For example, when parsing:

const userAgentData = {
  brands: [
    {
      brand: 'Not.A/Brand',
      version: '8',
    },
    {
      brand: 'Chromium',
      version: '114',
    },
    {
      brand: 'Google Chrome',
      version: '114',
    },
  ],
  mobile: true,
  platform: 'Android',
};

We get

const userAgent = {
  browser: {
    browserEngine: 'chrome',
    major: '114',
    name: 'chrome',
    version: '114',
  },
  cpu: {
    architecture: undefined,
  },
  device: {
    model: undefined,
    type: 'mobile',
    vendor: undefined,
  },
  engine: {
    name: 'Blink',
    version: '114',
  },
  mobileOS: 'android',
  os: {
    name: 'Android',
    version: undefined,
  },
  sameSiteNoneCompatible: true,
};

parseUserAgentHeader​

Used in the following cases:

  • Headers are unavailable on the server.
  • There were errors in obtaining navigator.userAgentData on the client.

The parseUserAgentHeader method parses the userAgent string and returns an object with browser data. For example, when parsing Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.61 Safari/537.36 We get

const userAgent = {
  browser: {
    browserEngine: 'chrome',
    major: '83',
    name: 'chrome',
    version: '83.0.4103.61',
  },
  cpu: {
    architecture: undefined,
  },
  device: {
    model: undefined,
    type: undefined,
    vendor: undefined,
  },
  engine: {
    name: 'Blink',
    version: '83.0.4103.61',
  },
  mobileOS: undefined,
  os: {
    name: 'Mac OS',
    version: '10.15.4',
  },
  sameSiteNoneCompatible: true,
};

isBrowserSatisfiesRequirements​

The function isBrowserSatisfiesRequirements checks if a given user agent satisfies the specified browser requirements based on a browserslist configuration. It parses the user agent to determine the browser and its version, normalizes the browserslist configuration, and compares the browser version against the specified requirements. The function returns true if the browser meets the requirements, false if it does not, and null if the browser is not found in the browserslist. It also handles special cases for Chromium-based browsers and allows forcing the use of minimum requested versions for browsers with incomplete statistics.