From b536c424d06b3effe8d50fc611563771915b2afc Mon Sep 17 00:00:00 2001 From: Denis Demchenko Date: Sun, 8 Jul 2018 12:41:10 +0300 Subject: [PATCH] Update README.md --- README.md | 188 +++++------------------------------------------------- 1 file changed, 15 insertions(+), 173 deletions(-) diff --git a/README.md b/README.md index c54e5ea..796358b 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,9 @@ A Browser detector. Because sometimes, there is no other way, and not even good [![bowser ci](https://secure.travis-ci.org/lancedikson/bowser.png)](https://travis-ci.org/lancedikson/bowser/) # Contents -- Overview -- Use cases -- API -- How can I help? +- [Overview](#overview) +- [Use cases](#use-cases) +- [How can I help?](#contributing) # Overview @@ -19,7 +18,7 @@ to filter the users somehow depending on their browsers. First of all, require the library: ``` -const Bowser = require('bowser'); +const bowser = require('bowser'); ``` ## Browser props detection @@ -28,7 +27,7 @@ Often we need to pick users' browser properties such as the name, the version, the rendering engine and so on. Here is an example how to make it with Bowser: ``` -const browser = new Bowser(window.navigator.userAgent); +const browser = bowser.getParser(window.navigator.userAgent); console.log(`The current browser name is "${browser.getBrowserName()}"`); // The current browser name is "Internet Explorer" @@ -39,7 +38,7 @@ or ``` const impression = new Impression(); -const browser = new Bowser(window.navigator.userAgent); +const browser = bowser.getParser(window.navigator.userAgent); const browserInfo = browser.getBrowser(); impression.brName = browserInfo.name; impression.brVer = browserInfo.version; @@ -48,7 +47,7 @@ impression.brVer = browserInfo.version; or ``` -const browser = new Bowser(window.navigator.userAgent); +const browser = bowser.getParser(window.navigator.userAgent); impression.userTechData = browser.parse(); console.log(impression.userTechData); // outputs @@ -80,8 +79,8 @@ support for them or make any workarounds. It could look like this: ``` -const browser = new Bowser(window.navigator.userAgent); -const isValidBrowser = bowser.compare({ +const browser = bowser.getParsers(window.navigator.userAgent); +const isValidBrowser = browser.satisfies({ // declare browsers per OS windows: { "internet explorer": ">10", @@ -103,178 +102,21 @@ const isValidBrowser = bowser.compare({ }); ``` -Settings for any particular OS has more priority and redefines settings of standalone browsers. +Settings for any particular OS or platform has more priority and redefines settings of standalone browsers. +Thus, you can define OS or platform specific rules and they will have more priority in the end. -### new Bowser(`:Object`) -Use it to get object with detected flags of your current browser. +More of API and possibilities you will find in the `docs` folder. -### bowser._detect(ua `:String`)`:Object` -Use it to get object with detected flags from User Agent string. - -### bowser.check(minVersions`:Object`, strictMode`:Boolean`, [ua]`:String`)`:Boolean` -Use it to check if browser is supported. In default non-strict mode any browser family not present in `minVersions` will pass the check (like Chrome in the third call in the sample bellow). When strict mode is enabled then any not specified browser family in `minVersions` will cause `check` to return `false` (in the sample it is the fourth call, the last one). - -``` js -/** - * in case of using IE10 - */ -bowser.check({msie: "11"}); // true -bowser.check({msie: "9.0"}); // false - -/** - * specific user agent - */ -bowser.check({chrome: "45"}, window.navigator.userAgent); // true - -/** - * but false in strict mode - */ -bowser.check({chrome: "45"}, true, window.navigator.userAgent); // false -``` - -### bowser.compareVersions(versions`:Array`)`:Number` -Use it to compare two versions. - -``` js -bowser.compareVersions(['9.0', '10']); -// -1 -``` - -### bowser.isUnsupportedBrowser(minVersions`:Object`, [strictMode]`:Boolean`, [ua]`:string`)`:Boolean` -Use it to check if browser is unsupported. - -``` js -bowser.isUnsupportedBrowser({msie: "10"}, window.navigator.userAgent); -// true / false -``` - -See more examples in [tests](test/test.js). - ---- - -## Bowser Flags -Your mileage may vary, but these flags should be set. See Contributing below. - -``` js -alert('Hello ' + bowser.name + ' ' + bowser.version); -``` - -### All detected browsers -These flags are set for all detected browsers: - -* `name` - A human readable name for this browser. E.g. 'Chrome', '' -* `version` - Version number for the browser. E.g. '32.0' - -For unknown browsers, Bowser makes a best guess from the UA string. So, these may not be set. - -### Rendering engine flags -If detected, one of these flags may be set to true: - - -Safari, Chrome and some other minor browsers will report that they have `webkit` engines. -Firefox and Seamonkey will report that they have `gecko` engines. - -``` js -if (bowser.webkit) { - // do stuff with safari & chrome & opera & android & blackberry & webos & silk -} -``` - -### Device flags -If detected, one of these flags may be set to true: - - * `mobile` - All detected mobile OSes are additionally flagged `mobile`, **unless it's a tablet** - * `tablet` - If a tablet device is detected, the flag `tablet` is **set instead of `mobile`**. - -### Browser flags -If detected, one of these flags may be set to true. The rendering engine flag is shown in []'s: - - * `chrome` - [`webkit`|`blink`] - * `firefox` - [`gecko`] - * `msie` - * `msedge` - * `safari` - [`webkit`] - * `android` - native browser - [`webkit`|`blink`] - * `ios` - native browser - [`webkit`] - * `opera` - [`blink` if >=15] - * `samsungBrowser` - [`blink`] - * `phantom` - [`webkit`] - * `blackberry` - native browser - [`webkit`] - * `webos` - native browser - [`webkit`] - * `silk` - Amazon Kindle browser - [`webkit`] - * `bada` - [`webkit`] - * `tizen` - [`webkit`] - * `seamonkey` - [`gecko`] - * `sailfish` - [`gecko`] - * `ucbrowser` — [`webkit`] - * `qupzilla` — [`webkit`] - * `vivaldi` — [`blink`] - * `sleipnir` — [`blink`] - * `kMeleon` — [`gecko`] - -For all detected browsers the browser version is set in the `version` field. - -### OS Flags -If detected, one of these flags may be set to true: - - * `mac` - * `windows` - other than Windows Phone - * `windowsphone` - * `linux` - other than `android`, `chromeos`, `webos`, `tizen`, and `sailfish` - * `chromeos` - * `android` - * `ios` - also sets one of `iphone`/`ipad`/`ipod` - * `blackberry` - * `firefoxos` - * `webos` - may also set `touchpad` - * `bada` - * `tizen` - * `sailfish` - -`osversion` may also be set: - - * `osversion` - for Android, iOS, MacOS, Windows, Windows Phone, WebOS, Bada, and Tizen. If included in UA string. - -iOS is always reported as `ios` and additionally as `iphone`/`ipad`/`ipod`, whichever one matches best. -If WebOS device is an HP TouchPad the flag `touchpad` is additionally set. - -### Browser capability grading -One of these flags may be set: - - * `a` - This browser has full capabilities - * `c` - This browser has degraded capabilities. Serve simpler version - * `x` - This browser has minimal capabilities and is probably not well detected. - -There is no `b`. For unknown browsers, none of these flags may be set. - -### Ender Support - -`package.json` - -``` json -"dependencies": { - "bowser": "x.x.x" -} -``` - -``` js -if (require('bowser').chrome) { - alert('Hello Silicon Valley') -} -``` - -### Contributing +# Contributing If you'd like to contribute a change to bowser, modify the files in `src/`, then run the following (you'll need node + npm installed): ``` sh $ npm install -$ make test +$ npm test ``` -Please do not check-in the built files `bowser.js` and `bowser.min.js` in pull requests. - ### Adding tests -See the list in `src/useragents.js` with example user agents and their expected bowser object. +See the list in `test/acceptance/useragentstrings.yml` with example user agents and their expected bowser object. Whenever you add support for new browsers or notice a bug / mismatch, please update the list and check if all tests are still passing.