@shopify/browser

@shopify/browser

A package providing a simple wrapper around ua-parser-js to make extracting browser information from user-agents less cumbersome.

Installation

$ yarn add @shopify/browser

You probably don't need this

Generally speaking, browser-sniffing can be an unreliable practice. Many words have been written about why it is a bad idea.

However, there are some cases where it is the best tool for the job. It can provide better user-experience by allowing you to differentially serve javascript bundles at varying levels of transpilation to different browsers. It can also aid in collecting and categorizing metrics to allow you to understand when error spikes or performance degradations are isolated to a single browser.

Regardless of the usecase for browser-sniffing, always keep in mind the limitations and spoofability of user-agents. If providing different bundles based on browser, be sure to always have a sane (and preferably as compatible as possible) default for unknown or otherwise unparseable user-agents. If collecting metrics, be on the lookout for data that does not make sense, or spikes of browsers marked as unknown. Providing different features based on browser-sniffing should almost always be avoided in favour of feature-detection.

Basic Usage

This library can be used both in a browser and in a NodeJS environment.

Browser usage

You can find the user-agent of the current browser by accessing navigator.userAgent. Passing this value to the constructor of Browser will allow you to use all of the class's convenience methods.

import {Browser} from '@shopify/browser';
const browser = new Browser({userAgent: navigator.userAgent});
document.body.innerHTML = `
  your browser is: ${browser.name} v${browser.version}
  ${browser.isMobile ? 'on a mobile device'}
`;

Node usage

You can find the user-agent of incoming requests by accessing the user-agent header. Many web frameworks also provide convenience methods for accessing it.

Passing this value to the constructor of Browser will allow you to use all of the class's convenience methods.

import Koa from 'koa';
import {Browser} from '@shopify/browser';
const app = new Koa();
app.use(ctx => {
  const userAgent = ctx.get('user-agent');
  const browser = new Browser({userAgent});
  ctx.body = `
    your browser is: ${browser.name} v${browser.version}
    ${browser.isMobile ? 'on a mobile device'}
  `;
});

API

The Browser class

The primary API of this package is the Browser class. This class represents information about an individual browser as gleaned from it's user-agent.

import {Browser} from '@shopify/browser';
const chromeUA =
  'Mozilla/5.0 (Linux; Android 6.0; ALE-L23 Build/HuaweiALE-L23) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Mobile Safari/537.36';
const browser = new Browser({userAgent: chromeUA});

The class provides a number of convenience methods and properties for categorizing the browser, detailed below.

name

The name of the browser.

const chromeUA =
  'Mozilla/5.0 (Linux; Android 6.0; ALE-L23 Build/HuaweiALE-L23) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Mobile Safari/537.36';
const browser = new Browser({userAgent: chromeUA}).name;
=>  'Chrome'

version

The (semver) version of the browser.

const chromeUA =
  'Mozilla/5.0 (Linux; Android 6.0; ALE-L23 Build/HuaweiALE-L23) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Mobile Safari/537.36';
const browser = new Browser({userAgent: chromeUA}).version;
=>  '69.0.3497.100'

majorVersion

The current major version of the browser.

const chromeUA =
  'Mozilla/5.0 (Linux; Android 6.0; ALE-L23 Build/HuaweiALE-L23) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Mobile Safari/537.36';
const browser = new Browser({userAgent: chromeUA}).majorVersion;
=>  '69'

unknown

Whether the browser is unknown to the parser.

const fakeUA = 'totally not real';
const browser = new Browser({userAgent: fakeUA}).unknown;
=>  true

isMobile

Whether the browser is a mobile browser.

const iOSUA = 'Mozilla/5.0 (iPhone; CPU iPhone OS 9_3_5 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13G36 Safari/601.1';
const browser = new Browser({userAgent: iOSUA}).isMobile;
=>  true

isDesktop

Whether the browser is a desktop (not mobile) browser.

const iOSUA = 'Mozilla/5.0 (iPhone; CPU iPhone OS 9_3_5 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13G36 Safari/601.1';
const browser = new Browser({userAgent: iOSUA}).isDesktop;
=>  false

os

The operating system the browser runs on.

const iOSUA = 'Mozilla/5.0 (iPhone; CPU iPhone OS 9_3_5 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13G36 Safari/601.1';
const browser = new Browser({userAgent: iOSUA}).os;
=>  'iOS'

isWindows

Whether the operating system of the browser is any version of windows.

const iOSUA = 'Mozilla/5.0 (iPhone; CPU iPhone OS 9_3_5 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13G36 Safari/601.1';
const browser = new Browser({userAgent: iOSUA}).isWindows;
=>  false

isMac

Whether the operating system of the browser is any version of macOS.

const iOSUA = 'Mozilla/5.0 (iPhone; CPU iPhone OS 9_3_5 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13G36 Safari/601.1';
const browser = new Browser({userAgent: iOSUA}).isMac;
=>  false

isSafari

Whether the operating system of the browser is any version of macOS.

const iOSUA = 'Mozilla/5.0 (iPhone; CPU iPhone OS 9_3_5 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13G36 Safari/601.1';
const browser = new Browser({userAgent: iOSUA}).isMac;
=>  true

isChrome

Whether the browser is any version of chrome.

const chromeUA =
  'Mozilla/5.0 (Linux; Android 6.0; ALE-L23 Build/HuaweiALE-L23) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Mobile Safari/537.36';
const browser = new Browser({userAgent: chromeUA}).isChrome;
=>  true

isAndroidChrome

Whether the browser is specifically an Android build of Chrome.

const chromeUA =
  'Mozilla/5.0 (Linux; Android 6.0; ALE-L23 Build/HuaweiALE-L23) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Mobile Safari/537.36';
const browser = new Browser({userAgent: chromeUA}).majorVersion;
=> true

isFirefox

Whether the browser is any version of Firefox.

const firefoxUA =
  'Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0';
const browser = new Browser({userAgent: firefoxUA}).isFirefox;
=>  true

isIE

Whether the browser is any version of Internet Explorer.

const ieUA =
  'Mozilla/5.0 (compatible; MSIE 9.0; Windows Phone OS 7.5; Trident/5.0; IEMobile/9.0)';
const browser = new Browser({userAgent: ieUA}).isIE;
=>  true

isEdge

Whether the browser is any version of edge.

const edgeUA = 'Mozilla/5.0 (Windows NT 10.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36 Edge/12.10136';
const browser = new Browser({userAgent: edgeUA}).isEdge;
=>  true

isNativeApp

Whether the browser is a Shopify Mobile web-view

const nativeAppUA = 'Shopify Mobile/iOS/9.3.1 (iPad8,1 Simulator/com.shopify.ShopifyInternal/10.1.2)';
const browser = new Browser({userAgent: nativeAppUA}).isNativeApp;
=>  true

asPlainObject()

Returns basic information about the browser as a readily serializable plain object.

const userAgent =
  'Mozilla/5.0 (Linux; Android 6.0; ALE-L23 Build/HuaweiALE-L23) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Mobile Safari/537.36';
new Browser({userAgent}).asPlainObject();
=> {
  name: 'Chrome',
  version: '69.0.3497.100',
  isMobile: true,
  isNativeApp: false,
  isDesktop: false,
}