useragent

README

User agent parsing

useragent is a library written in golang to parse user agent strings.

Usage

First install the library with:

go get xojoc.pw/useragent

useragent is simple to use. First parse a string with useragent.Parse and then access the fields of useragent.UserAgent for the required information. Example:

• Access fields

see godoc for the complete documentation.

How it works?

      Lasciate ogne speranza, voi ch'intrate. -Dante

Parsing user agent strings is a hell. There is no standard for user agent strings, so useragent must use some heuristics. The site http://www.useragentstring.com/ has been invaluable during development. Some relevant links are also:

• https://developer.mozilla.org/en-US/docs/Web/HTTP/Gecko_user_agent_string_reference
• https://developer.chrome.com/multidevice/user-agent
• https://developer.apple.com/library/safari/documentation/AppleApplications/Reference/SafariWebContent/OptimizingforSafarioniPhone/OptimizingforSafarioniPhone.html#//apple_ref/doc/uid/TP40006517-SW3
• http://blogs.msdn.com/b/ieinternals/archive/2013/09/21/internet-explorer-11-user-agent-string-ua-string-sniffing-compatibility-with-gecko-webkit.aspx
• http://docs.aws.amazon.com/silk/latest/developerguide/user-agent.html

for the supported user agents see:

• browsers: browser.go
• crawlers: crawler.go

If you think useragent doesn't parse correctly a particular user agent string, just open an issue :).

Why this library?

useragent doesn't just split the user agent string and look for specific strings like other parsers, but it has specific parser for the most common browsers/crawlers and falls back to a generic parser for everything else. Its main features are:

• Simple and stable API.
• High precision in detection of the most common browsers/crawlers.
• Detects mobile/tablet devices.
• OS detection.
• URL with more information about the user agent (usually it's the home page).
• Security level detection when reported by browsers.

Who?

useragent was written by Alexandru Cojocaru and uses blang/semver to parse versions.

Thanks a lot to @brendanwalters (from http://pendo.io) for the contributions.

Donate!

License

useragent is released under the GPLv3 or later, see COPYING.

Documentation

Overview

Package useragent parses a user agent string.

Index

• Constants
• type Security
  • func (s Security) String() string
• type Type
  • func (a Type) String() string
• type UserAgent
  • func Parse(uas string) *UserAgent
  • func (ua *UserAgent) String() string

Examples

• Parse
• Parse (Access)

Constants

const (
	OSAndroid = "Android"
	OSMacOS   = "Mac OS X"
	OSiOS     = "iOS"
	OSLinux   = "GNU/Linux"
	OSWindows = "Windows"
)

Types

type Security

type Security int

Some browsers may put security level information in their user agent string.

const (
	SecurityUnknown Security = iota
	SecurityNone
	SecurityWeak
	SecurityStrong
)

func (Security) String

func (s Security) String() string

type Type

type Type int

const (
	Unknown Type = iota
	Browser
	Crawler
	LinkChecker
	Validator
	FeedReader
	Library
)

func (Type) String

func (a Type) String() string

type UserAgent

type UserAgent struct {
	// The original user agent string.
	Original string
	Type     Type
	// The browser/crawler/etc. name. For example:
	//  Firefox, IceCat, Iceweasel
	//  Dillo
	//  Chrome
	//  MSIE
	//  Googlebot
	//   etc.
	// If the name is not known, Name will be `unknown'.
	Name    string
	Version semver.Version
	// The OS name. Can be one of:
	//  GNU/Linux
	//  FreeBSD
	//  OpenBSD
	//  NetBSD
	//  Windows
	//  Mac OS X
	//  Android
	//  Firefox OS
	//  CrOS
	//   etc.
	// If the os is not known, OS will be `unknown'.
	OS        string
	OSVersion semver.Version
	Security  Security
	// URL with more information about the user agent (in most cases it's the home page).
	// If unknown is nil.
	URL *url.URL
	// Is it a phone device?
	Mobile bool
	// Is it a tablet device?
	Tablet bool
}

func Parse

func Parse(uas string) *UserAgent

Try to extract information about an user agent from uas. Since user agent strings don't have a standard, this function uses heuristics.

Example

ua := Parse("Mozilla/5.0 (X11; Linux i686; rv:38.0) Gecko/20100101 Firefox/38.0")
fmt.Print(ua)

Output:

Type: Browser
Name: Firefox
Version: 38.0.0
OS: GNU/Linux
OSVersion: 0.0.0
Security: Unknown security
Mobile: false
Tablet: false

Example (Access)

ua := Parse("Mozilla/5.0 (X11; Linux i686; rv:38.0) Gecko/20100101 Firefox/38.0")
if ua == nil {
	log.Fatal("cannot parse user agent string")
}
fmt.Println(ua.Type)
fmt.Println(ua.Name)
fmt.Println(ua.Version)
fmt.Println(ua.OS)
if ua.Security != SecurityUnknown {
	fmt.Println(ua.Security)
}

Output:

Browser
Firefox
38.0.0
GNU/Linux

func (*UserAgent) String

func (ua *UserAgent) String() string