github_mirrors/ua-parser-js
3
0
Fork 1
mirror of https://github.com/faisalman/ua-parser-js.git synced 2025-09-27 16:08:47 +03:00
Code Issues Packages Projects Releases Wiki Activity

Update readme & IData explanations

Browse Source
This commit is contained in:
Faisal Salman 2023-04-09 15:54:46 +07:00
parent a8951ec282
commit 801c2409b3
5 changed files with 144 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
dist/ua-parser.min.js vendored
View File

File diff suppressed because one or more lines are too long

2
dist/ua-parser.pack.js vendored
View File

File diff suppressed because one or more lines are too long

127
readme.md
View File

@ -3,11 +3,13 @@
</p>
<p align="center">
<a href="https://travis-ci.org/faisalman/ua-parser-js"><img src="https://travis-ci.org/faisalman/ua-parser-js.svg?branch=master"></a>
<a href="https://www.npmjs.com/package/ua-parser-js"><img src="https://img.shields.io/npm/v/ua-parser-js.svg"></a>
<a href="https://www.npmjs.com/package/ua-parser-js"><img src="https://img.shields.io/npm/dw/ua-parser-js.svg"></a>
<a href="https://www.jsdelivr.com/package/npm/ua-parser-js"><img src="https://data.jsdelivr.com/v1/package/npm/ua-parser-js/badge"></a>
<a href="https://cdnjs.com/libraries/UAParser.js"><img src="https://img.shields.io/cdnjs/v/UAParser.js.svg"></a>
<a href="https://www.npmjs.com/package/ua-parser-js"><img src="https://img.shields.io/npm/dw/ua-parser-js?color=red&logo=npm&label=NPM%20DOWNLOADS&style=for-the-badge"></a>
<a href="https://www.jsdelivr.com/package/npm/ua-parser-js"><img src="https://img.shields.io/jsdelivr/gh/hw/faisalman/ua-parser-js?logo=jsdelivr&style=for-the-badge"></a>
<a href="https://github.com/faisalman/ua-parser-js"><img src="https://img.shields.io/github/stars/faisalman/ua-parser-js?color=yellow&logo=github&style=for-the-badge"></a>
<a href="https://bundlephobia.com/package/ua-parser-js@1.0.35"><img src="https://img.shields.io/bundlephobia/minzip/ua-parser-js?logo=hackthebox&logoColor=white&style=for-the-badge"/></a>
<a href="https://github.com/faisalman/ua-parser-js/graphs/contributors"><img src="https://img.shields.io/github/contributors/faisalman/ua-parser-js?color=purple&logo=githubsponsors&style=for-the-badge"></a>
<a href="https://www.npmjs.com/package/ua-parser-js"><img src="https://img.shields.io/npm/v/ua-parser-js.svg?logo=npm&color=red&style=for-the-badge"></a>
<a href="https://cdnjs.com/libraries/UAParser.js"><img src="https://img.shields.io/cdnjs/v/UAParser.js.svg?color=orange&style=for-the-badge"></a>
</p>
# UAParser.js
@ -47,39 +49,47 @@ JavaScript library to detect Browser, Engine, OS, CPU, and Device type/model fro
What's new & breaking, please read [CHANGELOG](changelog.md) before upgrading.
# Documentation
### UAParser([user-agent:string][,extensions:object][,headers:object(since@2.0)])
In the browser environment you dont need to pass the user-agent string to the function, you can just call the funtion and it should automatically get the string from the `window.navigator.userAgent`, but that is not the case in nodejs. The user-agent string must be passed in' nodejs for the function to work. Usually you can find the user agent in: `request.headers["user-agent"]`.
### `UAParser([user-agent:string][,extensions:object][,headers:object(since@2.0)]):IData`
In browser environment you don't need to pass the user-agent string to the function, as it should automatically get the string from the `window.navigator.userAgent`. Whereas in nodejs environment, the user-agent string must be passed in order for the function to work (usually you can find the user-agent in: `request.headers["user-agent"]`).
## Constructor
#### * `new UAParser([user-agent:string][,extensions:object][,headers:object(since@2.0)]):UAParser`
When you call `UAParser` with the `new` keyword, `UAParser` will return a new instance with an empty result object, you have to call one of the available methods to get the information from the user-agent string.
Like so:
* `new UAParser([user-agent:string][,extensions:object][,headers:object(since@2.0)])`
```js
let parser = new UAParser("your user-agent here"); // you need to pass the user-agent for nodejs
console.log(parser); // {}
let parserResults = parser.getResult();
console.log(parserResults);
/** {
"ua" : "",
"browser" : {},
"engine" : {},
"os" : {},
"device" : {},
"cpu" : {}
} */
/*
{
ua : "",
browser : {},
engine : {},
os : {},
device : {},
cpu : {}
}
*/
```
When you call UAParser without the `new` keyword, it will automatically call `getResult()` function and return the parsed results.
* `UAParser([user-agent:string][,extensions:object][,headers:object(since@2.0)])`
* returns result object `{ ua: '', browser: {}, cpu: {}, device: {}, engine: {}, os: {} }`
#### * `UAParser([user-agent:string][,extensions:object][,headers:object(since@2.0)]):IData`
## Methods
When you call `UAParser` without the `new` keyword, it will automatically call `getResult()` function and return the parsed results.
```sh
returns result object `{ ua: '', browser: {}, cpu: {}, device: {}, engine: {}, os: {} }`
```
## `UAParser`:
#### Methods table
The methods are self explanatory, here's a small overview on all the available methods:
* `getResult()` - returns all function object calls, user-agent string, browser info, cpu, device, engine, os:
* `getResult()` - returns all function object calls, user-agent string, browser info, cpu, device, engine, os:
`{ ua: '', browser: {}, cpu: {}, device: {}, engine: {}, os: {} }`.
* `getBrowser()` - returns the browser name and version.
@ -88,17 +98,21 @@ The methods are self explanatory, here's a small overview on all the available m
* `getOS()` - returns the running operating system name and version.
* `getCPU()` - returns CPU architectural design name.
* `getUA()` - returns the user-agent string.
* `setUA(user-agent)` - set a custom user-agent to be parsed.
* `setUA(ua)` - set a custom user-agent to be parsed.
---
* `getResult()`
* returns `{ ua: '', browser: {}, cpu: {}, device: {}, engine: {}, os: {} }`
* `getBrowser()`
* returns `{ name: '', version: '' }`
#### * `getResult():IData`
```sh
returns `{ ua: '', browser: {}, cpu: {}, device: {}, engine: {}, os: {} }`
```
#### * `getBrowser():IData`
```sh
returns `{ name: '', version: '' }`
# Possible 'browser.name':
2345Explorer, 360 Browser, Amaya, Android Browser, Arora, Avant, Avast, AVG,
BIDUBrowser, Baidu, Basilisk, Blazer, Bolt, Brave, Bowser, Camino, Chimera,
@ -119,10 +133,11 @@ Vivaldi, Waterfox, WeChat, Weibo, Yandex, baidu, iCab, w3m, Whale Browser, ...
# 'browser.version' determined dynamically
```
* `getDevice()`
* returns `{ model: '', type: '', vendor: '' }`
#### * `getDevice():IData`
```sh
returns `{ model: '', type: '', vendor: '' }`
# Possible 'device.type':
console, mobile, tablet, smarttv, wearable, embedded
@ -143,10 +158,11 @@ Siemens, Sony[Ericsson], Sprint, Tesla, Vivo, Vodafone, Xbox, Xiaomi, Zebra, ZTE
# 'device.model' determined dynamically
```
* `getEngine()`
* returns `{ name: '', version: '' }`
#### * `getEngine():IData`
```sh
returns `{ name: '', version: '' }`
# Possible 'engine.name'
Amaya, Blink, EdgeHTML, Flow, Gecko, Goanna, iCab, KHTML, LibWeb, Links, Lynx,
NetFront, NetSurf, Presto, Tasman, Trident, w3m, WebKit
@ -154,10 +170,11 @@ NetFront, NetSurf, Presto, Tasman, Trident, w3m, WebKit
# 'engine.version' determined dynamically
```
* `getOS()`
* returns `{ name: '', version: '' }`
#### * `getOS():IData`
```sh
returns `{ name: '', version: '' }`
# Possible 'os.name'
AIX, Amiga OS, Android[-x86], Arch, Bada, BeOS, BlackBerry, CentOS, Chromium OS,
Contiki, Fedora, Firefox OS, FreeBSD, Debian, Deepin, DragonFly, elementary OS,
@ -172,22 +189,42 @@ Zenwalk, ...
# 'os.version' determined dynamically
```
* `getCPU()`
* returns `{ architecture: '' }`
#### * `getCPU():IData`
```sh
returns `{ architecture: '' }`
# Possible 'cpu.architecture'
68k, amd64, arm[64/hf], avr, ia[32/64], irix[64], mips[64], pa-risc, ppc, sparc[64]
```
* `getUA()`
* returns UA string of current instance
#### * `getUA():string`
* `setUA(uastring)`
* set UA string to be parsed
* returns current instance
```sh
returns user-agent string of current instance
```
#### * `is():boolean` utility `since@2.0`
#### * `setUA(ua:string):UAParser`
```sh
set user-agent string to be parsed
returns current instance
```
---
## `IData`: `since@2.0`
#### Methods table
The methods are self explanatory, here's a small overview on all the available methods:
* `is(value)` - returns `true` if the passed value matches a value of current object, `false` otherwise
* `toString()` - returns the full-name values of current object as a string
* `withClientHints()` - returns an object with re-updated data from client hints
* `withFeatureCheck()` - returns an object with re-updated data from feature detection
---
#### * `is(value:string):boolean`
```js
// Is just a shorthand comparison to check whether the value of specified item equals one of its properties (in a case-insensitive way)
@ -246,7 +283,7 @@ let engine = uap.getEngine();
engine.is("Blink"); // true
```
#### * `toString():string` utility `since@2.0`
#### * `toString():string`
```js
// Retrieve full-name values as a string
@ -287,7 +324,7 @@ engine.version; // "28.0.1500.95"
engine.toString(); // "Blink 28.0.1500.95"
```
#### * `withClientHints():Promise<object>|Thenable<object>|object` `since@2.0`
#### * `withClientHints():Promise<IData>|Thenable<IData>|IData`
Recently, Chrome limits the information exposed through user-agent and introduces a new experimental set of data called "client-hints". In browser-environment, obtaining the client-hints data via JavaScript must be done in an asynchronous way. In `UAParser` you can chain the result object from `get*` method with `withClientHints()` to also read the client-hints data from the browser and return the updated data as a `Promise`.
@ -346,7 +383,7 @@ new UAParser(request.headers)
});
```
#### * `withFeatureCheck():object` `since@2.0`
#### * `withFeatureCheck():IData`
This method allows us to examine other features beyond `navigator.userAgent` to further improve detection of the following:
- browser : Brave (check for `navigator.isBrave`)

62
src/module/ua-parser.mjs
View File

@ -829,22 +829,22 @@
return props;
})();
var createUAParserData = function (item, itemType) {
var createIData = function (item, itemType) {
var init_props = defaultProps.init[itemType],
is_ignoreProps = defaultProps.isIgnore[itemType] || 0,
is_ignoreRgx = defaultProps.isIgnoreRgx[itemType] || 0,
toString_props = defaultProps.toString[itemType] || 0;
function UAParserData () {
function IData () {
setProps.call(this, init_props);
}
UAParserData.prototype.getItem = function () {
IData.prototype.getItem = function () {
return item;
};
UAParserData.prototype.withClientHints = function () {
IData.prototype.withClientHints = function () {
// nodejs / non-client-hints browsers
if (!NAVIGATOR_UADATA) {
@ -858,14 +858,18 @@
.getHighEntropyValues(CH_ALL_VALUES)
.then(function (res) {
return item
.setCH(new UAParserDataCH(res, false))
.setCH(new UACHData(res, false))
.parseCH()
.get();
});
};
IData.prototype.withFeatureCheck = function () {
return item.detectFeature().get();
};
if (itemType != UA_RESULT) {
UAParserData.prototype.is = function (strToCheck) {
IData.prototype.is = function (strToCheck) {
var is = false;
for (var i in this) {
if (this.hasOwnProperty(i) && !has(is_ignoreProps, i) && lowerize(is_ignoreRgx ? strip(is_ignoreRgx, this[i]) : this[i]) == lowerize(is_ignoreRgx ? strip(is_ignoreRgx, strToCheck) : strToCheck)) {
@ -878,7 +882,7 @@
}
return is;
};
UAParserData.prototype.toString = function () {
IData.prototype.toString = function () {
var str = EMPTY;
for (var i in toString_props) {
if (typeof(this[toString_props[i]]) !== UNDEF_TYPE) {
@ -890,33 +894,33 @@
}
if (!NAVIGATOR_UADATA) {
UAParserData.prototype.then = function (cb) {
IData.prototype.then = function (cb) {
var that = this;
var UAParserDataResolve = function () {
var IDataResolve = function () {
for (var prop in that) {
if (that.hasOwnProperty(prop)) {
this[prop] = that[prop];
}
}
};
UAParserDataResolve.prototype = {
is : UAParserData.prototype.is,
toString : UAParserData.prototype.toString
IDataResolve.prototype = {
is : IData.prototype.is,
toString : IData.prototype.toString
};
var resolveData = new UAParserDataResolve();
var resolveData = new IDataResolve();
cb(resolveData);
return resolveData;
};
}
return new UAParserData();
return new IData();
};
/////////////////
// Constructor
////////////////
function UAParserDataCH (uach, isHTTP_UACH) {
function UACHData (uach, isHTTP_UACH) {
uach = uach || {};
setProps.call(this, CH_ALL_VALUES);
if (isHTTP_UACH) {
@ -938,7 +942,7 @@
}
}
function UAParserItem (itemType, ua, rgxMap, uaCH) {
function UAItem (itemType, ua, rgxMap, uaCH) {
this.get = function (prop) {
if (!prop) return this.data;
@ -980,6 +984,20 @@
if (!this.get(NAME) && NAVIGATOR_UADATA && NAVIGATOR_UADATA[PLATFORM]) {
this.set(NAME, NAVIGATOR_UADATA[PLATFORM]);
}
break;
case UA_RESULT:
var data = this.data;
var detect = function (itemType) {
return data[itemType]
.getItem()
.detectFeature()
.get();
};
this.set(UA_BROWSER, detect(UA_BROWSER))
.set(UA_CPU, detect(UA_CPU))
.set(UA_DEVICE, detect(UA_DEVICE))
.set(UA_ENGINE, detect(UA_ENGINE))
.set(UA_OS, detect(UA_OS));
}
}
return this;
@ -1048,8 +1066,7 @@
.parseCH()
.get();
};
this.set('ua', ua)
.set(UA_BROWSER, parse(UA_BROWSER))
this.set(UA_BROWSER, parse(UA_BROWSER))
.set(UA_CPU, parse(UA_CPU))
.set(UA_DEVICE, parse(UA_DEVICE))
.set(UA_ENGINE, parse(UA_ENGINE))
@ -1063,7 +1080,7 @@
['ua', ua],
['uaCH', uaCH],
['rgxMap', rgxMap],
['data', createUAParserData(this, itemType)]
['data', createIData(this, itemType)]
]);
return this;
@ -1098,7 +1115,7 @@
headers[USER_AGENT] :
EMPTY)),
HTTP_UACH = new UAParserDataCH(headers, true),
HTTP_UACH = new UACHData(headers, true),
regexMap = extensions ?
extend(defaultRegexes, extensions) :
@ -1107,7 +1124,7 @@
createItemFunc = function (itemType) {
if (itemType == UA_RESULT) {
return function () {
return new UAParserItem(itemType, userAgent, regexMap, HTTP_UACH)
return new UAItem(itemType, userAgent, regexMap, HTTP_UACH)
.set('ua', userAgent)
.set(UA_BROWSER, this.getBrowser())
.set(UA_CPU, this.getCPU())
@ -1118,9 +1135,8 @@
};
} else {
return function () {
return new UAParserItem(itemType, userAgent, regexMap[itemType], HTTP_UACH)
return new UAItem(itemType, userAgent, regexMap[itemType], HTTP_UACH)
.parseUA()
.detectFeature()
.get();
};
}

42
src/ua-parser.js
View File

@ -827,22 +827,22 @@
return props;
})();
var createUAParserData = function (item, itemType) {
var createIData = function (item, itemType) {
var init_props = defaultProps.init[itemType],
is_ignoreProps = defaultProps.isIgnore[itemType] || 0,
is_ignoreRgx = defaultProps.isIgnoreRgx[itemType] || 0,
toString_props = defaultProps.toString[itemType] || 0;
function UAParserData () {
function IData () {
setProps.call(this, init_props);
}
UAParserData.prototype.getItem = function () {
IData.prototype.getItem = function () {
return item;
};
UAParserData.prototype.withClientHints = function () {
IData.prototype.withClientHints = function () {
// nodejs / non-client-hints browsers
if (!NAVIGATOR_UADATA) {
@ -856,18 +856,18 @@
.getHighEntropyValues(CH_ALL_VALUES)
.then(function (res) {
return item
.setCH(new UAParserDataCH(res, false))
.setCH(new UACHData(res, false))
.parseCH()
.get();
});
};
UAParserData.prototype.withFeatureCheck = function () {
IData.prototype.withFeatureCheck = function () {
return item.detectFeature().get();
};
if (itemType != UA_RESULT) {
UAParserData.prototype.is = function (strToCheck) {
IData.prototype.is = function (strToCheck) {
var is = false;
for (var i in this) {
if (this.hasOwnProperty(i) && !has(is_ignoreProps, i) && lowerize(is_ignoreRgx ? strip(is_ignoreRgx, this[i]) : this[i]) == lowerize(is_ignoreRgx ? strip(is_ignoreRgx, strToCheck) : strToCheck)) {
@ -880,7 +880,7 @@
}
return is;
};
UAParserData.prototype.toString = function () {
IData.prototype.toString = function () {
var str = EMPTY;
for (var i in toString_props) {
if (typeof(this[toString_props[i]]) !== UNDEF_TYPE) {
@ -892,33 +892,33 @@
}
if (!NAVIGATOR_UADATA) {
UAParserData.prototype.then = function (cb) {
IData.prototype.then = function (cb) {
var that = this;
var UAParserDataResolve = function () {
var IDataResolve = function () {
for (var prop in that) {
if (that.hasOwnProperty(prop)) {
this[prop] = that[prop];
}
}
};
UAParserDataResolve.prototype = {
is : UAParserData.prototype.is,
toString : UAParserData.prototype.toString
IDataResolve.prototype = {
is : IData.prototype.is,
toString : IData.prototype.toString
};
var resolveData = new UAParserDataResolve();
var resolveData = new IDataResolve();
cb(resolveData);
return resolveData;
};
}
return new UAParserData();
return new IData();
};
/////////////////
// Constructor
////////////////
function UAParserDataCH (uach, isHTTP_UACH) {
function UACHData (uach, isHTTP_UACH) {
uach = uach || {};
setProps.call(this, CH_ALL_VALUES);
if (isHTTP_UACH) {
@ -940,7 +940,7 @@
}
}
function UAParserItem (itemType, ua, rgxMap, uaCH) {
function UAItem (itemType, ua, rgxMap, uaCH) {
this.get = function (prop) {
if (!prop) return this.data;
@ -1078,7 +1078,7 @@
['ua', ua],
['uaCH', uaCH],
['rgxMap', rgxMap],
['data', createUAParserData(this, itemType)]
['data', createIData(this, itemType)]
]);
return this;
@ -1113,7 +1113,7 @@
headers[USER_AGENT] :
EMPTY)),
HTTP_UACH = new UAParserDataCH(headers, true),
HTTP_UACH = new UACHData(headers, true),
regexMap = extensions ?
extend(defaultRegexes, extensions) :
@ -1122,7 +1122,7 @@
createItemFunc = function (itemType) {
if (itemType == UA_RESULT) {
return function () {
return new UAParserItem(itemType, userAgent, regexMap, HTTP_UACH)
return new UAItem(itemType, userAgent, regexMap, HTTP_UACH)
.set('ua', userAgent)
.set(UA_BROWSER, this.getBrowser())
.set(UA_CPU, this.getCPU())
@ -1133,7 +1133,7 @@
};
} else {
return function () {
return new UAParserItem(itemType, userAgent, regexMap[itemType], HTTP_UACH)
return new UAItem(itemType, userAgent, regexMap[itemType], HTTP_UACH)
.parseUA()
.get();
};