uasurfer

README

uasurfer

User Agent Surfer (uasurfer) is a lightweight Golang package that parses and abstracts HTTP User-Agent strings with particular attention to device type.

The following information is returned by uasurfer from a raw HTTP User-Agent string:

Name	Example	Coverage in 192,792 parses
Browser name	chrome	99.85%
Browser version	53	99.17%
Platform	ipad	99.97%
OS name	ios	99.96%
OS version	10	98.81%
Device type	tablet	99.98%

Layout engine, browser language, and other esoteric attributes are not parsed.

Coverage is estimated from a random sample of real UA strings collected across thousands of sources in US and EU mid-2016.

Usage

Parse(ua string) Function

The Parse() function accepts a user agent string and returns UserAgent struct with named constants and integers for versions (minor, major and patch separately), and the full UA string that was parsed (lowercase). A string can be retrieved by adding .String() to a variable, such as uasurfer.BrowserName.String().

// Define a user agent string
myUA := "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.85 Safari/537.36"

// Parse() returns all attributes, including returning the full UA string last
ua, uaString := uasurfer.Parse(myUA)

where example UserAgent is:

{
    Browser {
        BrowserName: BrowserChrome,
        Version: {
            Major: 45,
            Minor: 0,
            Patch: 2454,
        },
    },
    OS {
        Platform: PlatformMac,
        Name: OSMacOSX,
        Version: {
            Major: 10,
            Minor: 10,
            Patch: 5,
        },
    },
    DeviceType: DeviceComputer,
}

Usage note: There are some OSes that do not return a version, see docs below. Linux is typically not reported with a specific Linux distro name or version.

Browser Name

• BrowserChrome - Google Chrome, Chromium
• BrowserSafari - Apple Safari, Google Search (GSA)
• BrowserIE - Microsoft Internet Explorer, Edge
• BrowserFirefox - Mozilla Firefox, GNU IceCat, Iceweasel, Seamonkey
• BrowserAndroid - Android WebView (Android OS <4.4 only)
• BrowserOpera - Opera
• BrowserUCBrowser - UC Browser
• BrowserSilk - Amazon Silk
• BrowserQQ - Tencent QQ
• BrowserSpotify - Spotify desktop client
• BrowserBlackberry - RIM BlackBerry
• BrowserYandex - Yandex
• BrowserNintendo - Nintendo DS(i) Browser
• BrowserSamsung - Samsung Internet
• BrowserCocCoc- Cốc Cốc
• BrowserUnknown - Unknown

Browser Version

Browser version returns an unint8 of the major version attribute of the User-Agent String. For example Chrome 45.0.23423 would return 45. The intention is to support math operators with versions, such as "do XYZ for Chrome version >23".

Unknown version is returned as 0.

Platform

• PlatformWindows - Microsoft Windows
• PlatformMac - Apple Macintosh
• PlatformLinux - Linux, including Android and other OSes
• PlatformiPad - Apple iPad
• PlatformiPhone - Apple iPhone
• PlatformBlackberry - RIM Blackberry
• PlatformWindowsPhone Microsoft Windows Phone & Mobile
• PlatformKindle - Amazon Kindle & Kindle Fire
• PlatformPlaystation - Sony Playstation, Vita, PSP
• PlatformXbox - Microsoft Xbox
• PlatformNintendo - Nintendo DS, Wii, etc.
• PlatformUnknown - Unknown

OS Name

• OSWindows
• OSMacOSX - includes "macOS Sierra"
• OSiOS
• OSAndroid
• OSChromeOS
• OSWebOS
• OSLinux
• OSPlaystation
• OSXbox
• OSNintendo
• OSUnknown

OS Version

OS X major version is always 10 for releases prior to Big Sur with consecutive minor versions indicating release releases (10 - Yosemite, 11 - El Capitain, 12 Sierra, etc). macOS Big Sur is indicated as {11, 1, 0}. Windows version is NT version. Version{0, 0, 0} indicated version is unknown or not evaluated. Versions can be compared using Less function: if ver1.Less(ver2) {}

Here are some examples across the platform, os.name, and os.version:

• For Windows XP (Windows NT 5.1), "PlatformWindows" is the platform, "OSWindows" is the name, and {5, 1, 0} the version.
• For OS X 10.5.1, "PlatformMac" is the platform, "OSMacOSX" the name, and {10, 5, 1} the version.
• For Android 5.1, "PlatformLinux" is the platform, "OSAndroid" is the name, and {5, 1, 0} the version.
• For iOS 5.1, "PlatformiPhone" or "PlatformiPad" is the platform, "OSiOS" is the name, and {5, 1, 0} the version.

Windows Version Guide

• Windows 10 - {10, 0, 0}
• Windows 8.1 - {6, 3, 0}
• Windows 8 - {6, 2, 0}
• Windows 7 - {6, 1, 0}
• Windows Vista - {6, 0, 0}
• Windows XP - {5, 1, 0} or {5, 2, 0}
• Windows 2000 - {5, 0, 0}

Windows 95, 98, and ME represent 0.01% of traffic worldwide and are not available through this package at this time.

DeviceType

DeviceType is typically quite accurate, though determining between phones and tablets on Android is not always possible due to how some vendors design their UA strings. A mobile Android device without tablet indicator defaults to being classified as a phone. DeviceTV supports major brands such as Philips, Sharp, Vizio and steaming boxes such as Apple, Google, Roku, Amazon.

• DeviceComputer
• DevicePhone
• DeviceTablet
• DeviceTV
• DeviceConsole
• DeviceWearable
• DeviceUnknown

Example Combinations of Attributes

• Surface RT -> OSWindows8, DeviceTablet, OSVersion >= 6
• Android Tablet -> OSAndroid, DeviceTablet
• Microsoft Edge -> BrowserIE, BrowserVersion >= 12.0.0

To do

• Remove compiled regexp in favor of string.Contains wherever possible (lowers mem/alloc)
• Better version support on Firefox derivatives (e.g. SeaMonkey)
• Potential additional browser support:
• "NetFront" (1% share in India)
• "Sogou Explorer" (5% share in China)
• "Maxthon" (1.5% share in China)
• "Nokia"
• Potential additional OS support:
• "Nokia" (5% share in India)
• "Series 40" (5.5% share in India)
• Windows 2003 Server
• iOS safari browser identification based on iOS version
• Add android version to browser identification
• old Macs
• "opera/9.64 (macintosh; ppc mac os x; u; en) presto/2.1.1"
• old Windows
• "mozilla/5.0 (windows nt 4.0; wow64) applewebkit/537.36 (khtml, like gecko) chrome/37.0.2049.0 safari/537.36"

Documentation

Overview

Package uasurfer provides fast and reliable abstraction of HTTP User-Agent strings. The philosophy is to identify technologies that holds >1% market share, and to avoid expending resources and accuracy on guessing at esoteric UA strings.

Index

• func ParseUserAgent(ua string, dest *UserAgent)
• type Browser
• type BrowserName
  • func (i BrowserName) String() string
  • func (b BrowserName) StringTrimPrefix() string
• type DeviceType
  • func (i DeviceType) String() string
  • func (d DeviceType) StringTrimPrefix() string
• type OS
• type OSName
  • func (i OSName) String() string
  • func (o OSName) StringTrimPrefix() string
• type Platform
  • func (i Platform) String() string
  • func (p Platform) StringTrimPrefix() string
• type UserAgent
  • func Parse(ua string) *UserAgent
  • func (ua *UserAgent) IsBot() bool
  • func (ua *UserAgent) Reset()
• type Version
  • func (v Version) Less(c Version) bool

Functions

func ParseUserAgent

func ParseUserAgent(ua string, dest *UserAgent)

ParseUserAgent is the same as Parse, but populates the supplied UserAgent. It is the caller's responsibility to call Reset() on the UserAgent before passing it to this function.

Types

type Browser

type Browser struct {
	Name    BrowserName
	Version Version
}

type BrowserName

type BrowserName int

BrowserName (int) returns a constant.

const (
	BrowserUnknown BrowserName = iota
	BrowserChrome
	BrowserIE
	BrowserSafari
	BrowserFirefox
	BrowserAndroid
	BrowserOpera
	BrowserBlackberry
	BrowserUCBrowser
	BrowserSilk
	BrowserNokia
	BrowserNetFront
	BrowserQQ
	BrowserMaxthon
	BrowserSogouExplorer
	BrowserSpotify
	BrowserNintendo
	BrowserSamsung
	BrowserYandex
	BrowserCocCoc
	BrowserBot // Bot list begins here
	BrowserAppleBot
	BrowserBaiduBot
	BrowserBingBot
	BrowserDuckDuckGoBot
	BrowserFacebookBot
	BrowserGoogleBot
	BrowserLinkedInBot
	BrowserMsnBot
	BrowserPingdomBot
	BrowserTwitterBot
	BrowserYandexBot
	BrowserCocCocBot
	BrowserYahooBot // Bot list ends here
)

A complete list of supported web browsers in the form of constants.

func (BrowserName) String

func (i BrowserName) String() string

func (BrowserName) StringTrimPrefix

func (b BrowserName) StringTrimPrefix() string

StringTrimPrefix is like String() but trims the "Browser" prefix

type DeviceType

type DeviceType int

DeviceType (int) returns a constant.

const (
	DeviceUnknown DeviceType = iota
	DeviceComputer
	DeviceTablet
	DevicePhone
	DeviceConsole
	DeviceWearable
	DeviceTV
)

A complete list of supported devices in the form of constants.

func (DeviceType) String

func (i DeviceType) String() string

func (DeviceType) StringTrimPrefix

func (d DeviceType) StringTrimPrefix() string

StringTrimPrefix is like String() but trims the "Device" prefix

type OS

type OS struct {
	Platform Platform
	Name     OSName
	Version  Version
}

type OSName

type OSName int

OSName (int) returns a constant.

const (
	OSUnknown OSName = iota
	OSWindowsPhone
	OSWindows
	OSMacOSX
	OSiOS
	OSAndroid
	OSBlackberry
	OSChromeOS
	OSKindle
	OSWebOS
	OSLinux
	OSPlaystation
	OSXbox
	OSNintendo
	OSBot
)

A complete list of supported OSes in the form of constants. For handling particular versions of operating systems (e.g. Windows 2000), see the README.md file.

func (OSName) String

func (i OSName) String() string

func (OSName) StringTrimPrefix

func (o OSName) StringTrimPrefix() string

StringTrimPrefix is like String() but trims the "OS" prefix

type Platform

type Platform int

Platform (int) returns a constant.

const (
	PlatformUnknown Platform = iota
	PlatformWindows
	PlatformMac
	PlatformLinux
	PlatformiPad
	PlatformiPhone
	PlatformiPod
	PlatformBlackberry
	PlatformWindowsPhone
	PlatformPlaystation
	PlatformXbox
	PlatformNintendo
	PlatformBot
)

A complete list of supported platforms in the form of constants. Many OSes report their true platform, such as Android OS being Linux platform.

func (Platform) String

func (i Platform) String() string

func (Platform) StringTrimPrefix

func (p Platform) StringTrimPrefix() string

StringTrimPrefix is like String() but trims the "Platform" prefix

type UserAgent

type UserAgent struct {
	Browser    Browser
	OS         OS
	DeviceType DeviceType
}

func Parse

func Parse(ua string) *UserAgent

Parse accepts a raw user agent (string) and returns the UserAgent.

func (*UserAgent) IsBot

func (ua *UserAgent) IsBot() bool

IsBot returns true if the UserAgent represent a bot

func (*UserAgent) Reset

func (ua *UserAgent) Reset()

Reset resets the UserAgent to it's zero value

type Version

type Version struct {
	Major int
	Minor int
	Patch int
}

func (Version) Less

func (v Version) Less(c Version) bool