1[![Build Status](https://travis-ci.org/avct/uasurfer.svg?branch=master)](https://travis-ci.org/avct/uasurfer) [![GoDoc](https://godoc.org/github.com/avct/uasurfer?status.svg)](https://godoc.org/github.com/avct/uasurfer) [![Go Report Card](https://goreportcard.com/badge/github.com/avct/uasurfer)](https://goreportcard.com/report/github.com/avct/uasurfer) 2 3# uasurfer 4 5![uasurfer-100px](https://cloud.githubusercontent.com/assets/597902/16172506/9debc136-357a-11e6-90fb-c7c46f50dff0.png) 6 7**User Agent Surfer** (uasurfer) is a lightweight Golang package that parses and abstracts [HTTP User-Agent strings](https://en.wikipedia.org/wiki/User_agent) with particular attention to device type. 8 9The following information is returned by uasurfer from a raw HTTP User-Agent string: 10 11| Name | Example | Coverage in 192,792 parses | 12|----------------|---------|--------------------------------| 13| Browser name | `chrome` | 99.85% | 14| Browser version | `53` | 99.17% | 15| Platform | `ipad` | 99.97% | 16| OS name | `ios` | 99.96% | 17| OS version | `10` | 98.81% | 18| Device type | `tablet` | 99.98% | 19 20Layout engine, browser language, and other esoteric attributes are not parsed. 21 22Coverage is estimated from a random sample of real UA strings collected across thousands of sources in US and EU mid-2016. 23 24## Usage 25 26### Parse(ua string) Function 27 28The `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()`. 29 30``` 31// Define a user agent string 32myUA := "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" 33 34// Parse() returns all attributes, including returning the full UA string last 35ua, uaString := uasurfer.Parse(myUA) 36``` 37 38where example UserAgent is: 39``` 40{ 41 Browser { 42 BrowserName: BrowserChrome, 43 Version: { 44 Major: 45, 45 Minor: 0, 46 Patch: 2454, 47 }, 48 }, 49 OS { 50 Platform: PlatformMac, 51 Name: OSMacOSX, 52 Version: { 53 Major: 10, 54 Minor: 10, 55 Patch: 5, 56 }, 57 }, 58 DeviceType: DeviceComputer, 59} 60``` 61 62**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. 63 64#### Browser Name 65* `BrowserChrome` - Google [Chrome](https://en.wikipedia.org/wiki/Google_Chrome), [Chromium](https://en.wikipedia.org/wiki/Chromium_(web_browser)) 66* `BrowserSafari` - Apple [Safari](https://en.wikipedia.org/wiki/Safari_(web_browser)), Google Search ([GSA](https://itunes.apple.com/us/app/google/id284815942)) 67* `BrowserIE` - Microsoft [Internet Explorer](https://en.wikipedia.org/wiki/Internet_Explorer), [Edge](https://en.wikipedia.org/wiki/Microsoft_Edge) 68* `BrowserFirefox` - Mozilla [Firefox](https://en.wikipedia.org/wiki/Firefox), GNU [IceCat](https://en.wikipedia.org/wiki/GNU_IceCat), [Iceweasel](https://en.wikipedia.org/wiki/Mozilla_Corporation_software_rebranded_by_the_Debian_project#Iceweasel), [Seamonkey](https://en.wikipedia.org/wiki/SeaMonkey) 69* `BrowserAndroid` - Android [WebView](https://developer.chrome.com/multidevice/webview/overview) (Android OS <4.4 only) 70* `BrowserOpera` - [Opera](https://en.wikipedia.org/wiki/Opera_(web_browser)) 71* `BrowserUCBrowser` - [UC Browser](https://en.wikipedia.org/wiki/UC_Browser) 72* `BrowserSilk` - Amazon [Silk](https://en.wikipedia.org/wiki/Amazon_Silk) 73* `BrowserQQ` - Tencent [QQ](https://en.wikipedia.org/wiki/Tencent_QQ) 74* `BrowserSpotify` - [Spotify](https://en.wikipedia.org/wiki/Spotify#Clients) desktop client 75* `BrowserBlackberry` - RIM [BlackBerry](https://en.wikipedia.org/wiki/BlackBerry) 76* `BrowserYandex` - [Yandex](https://en.wikipedia.org/wiki/Yandex_Browser) 77* `BrowserNintendo` - [Nintendo DS(i) Browser](https://en.wikipedia.org/wiki/Nintendo_DS_%26_DSi_Browser) 78* `BrowserSamsung` - [Samsung Internet](https://en.wikipedia.org/wiki/Samsung_Internet_for_Android) 79* `BrowserCocCoc`- [Cốc Cốc](https://en.wikipedia.org/wiki/C%E1%BB%91c_C%E1%BB%91c) 80* `BrowserUnknown` - Unknown 81 82#### Browser Version 83 84Browser 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". 85 86Unknown version is returned as `0`. 87 88#### Platform 89* `PlatformWindows` - Microsoft Windows 90* `PlatformMac` - Apple Macintosh 91* `PlatformLinux` - Linux, including Android and other OSes 92* `PlatformiPad` - Apple iPad 93* `PlatformiPhone` - Apple iPhone 94* `PlatformBlackberry` - RIM Blackberry 95* `PlatformWindowsPhone` Microsoft Windows Phone & Mobile 96* `PlatformKindle` - Amazon Kindle & Kindle Fire 97* `PlatformPlaystation` - Sony Playstation, Vita, PSP 98* `PlatformXbox` - Microsoft Xbox 99* `PlatformNintendo` - Nintendo DS, Wii, etc. 100* `PlatformUnknown` - Unknown 101 102#### OS Name 103* `OSWindows` 104* `OSMacOSX` - includes "macOS Sierra" 105* `OSiOS` 106* `OSAndroid` 107* `OSChromeOS` 108* `OSWebOS` 109* `OSLinux` 110* `OSPlaystation` 111* `OSXbox` 112* `OSNintendo` 113* `OSUnknown` 114 115#### OS Version 116 117OS X major version is alway 10 with consecutive minor versions indicating release releases (10 - Yosemite, 11 - El Capitain, 12 Sierra, etc). Windows version is NT version. `Version{0, 0, 0}` indicated version is unknown or not evaluated. 118Versions can be compared using `Less` function: `if ver1.Less(ver2) {}` 119 120Here are some examples across the platform, os.name, and os.version: 121 122* For Windows XP (Windows NT 5.1), "`PlatformWindows`" is the platform, "`OSWindows`" is the name, and `{5, 1, 0}` the version. 123* For OS X 10.5.1, "`PlatformMac`" is the platform, "`OSMacOSX`" the name, and `{10, 5, 1}` the version. 124* For Android 5.1, "`PlatformLinux`" is the platform, "`OSAndroid`" is the name, and `{5, 1, 0}` the version. 125* For iOS 5.1, "`PlatformiPhone`" or "`PlatformiPad`" is the platform, "`OSiOS`" is the name, and `{5, 1, 0}` the version. 126 127###### Windows Version Guide 128 129* Windows 10 - `{10, 0, 0}` 130* Windows 8.1 - `{6, 3, 0}` 131* Windows 8 - `{6, 2, 0}` 132* Windows 7 - `{6, 1, 0}` 133* Windows Vista - `{6, 0, 0}` 134* Windows XP - `{5, 1, 0}` or `{5, 2, 0}` 135* Windows 2000 - `{5, 0, 0}` 136 137Windows 95, 98, and ME represent 0.01% of traffic worldwide and are not available through this package at this time. 138 139#### DeviceType 140DeviceType 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. 141 142* `DeviceComputer` 143* `DevicePhone` 144* `DeviceTablet` 145* `DeviceTV` 146* `DeviceConsole` 147* `DeviceWearable` 148* `DeviceUnknown` 149 150## Example Combinations of Attributes 151* Surface RT -> `OSWindows8`, `DeviceTablet`, OSVersion >= `6` 152* Android Tablet -> `OSAndroid`, `DeviceTablet` 153* Microsoft Edge -> `BrowserIE`, BrowserVersion >= `12.0.0` 154 155## To do 156 157* Remove compiled regexp in favor of string.Contains wherever possible (lowers mem/alloc) 158* Better version support on Firefox derivatives (e.g. SeaMonkey) 159* Potential additional browser support: 160 * "NetFront" (1% share in India) 161 * "Sogou Explorer" (5% share in China) 162 * "Maxthon" (1.5% share in China) 163 * "Nokia" 164* Potential additional OS support: 165 * "Nokia" (5% share in India) 166 * "Series 40" (5.5% share in India) 167 * Windows 2003 Server 168* iOS safari browser identification based on iOS version 169* Add android version to browser identification 170* old Macs 171 * "opera/9.64 (macintosh; ppc mac os x; u; en) presto/2.1.1" 172* old Windows 173 * "mozilla/5.0 (windows nt 4.0; wow64) applewebkit/537.36 (khtml, like gecko) chrome/37.0.2049.0 safari/537.36" 174