Add new method: withClientHints() #408 #566 #588

readme.md

@@ -12,7 +12,7 @@
 
 # UAParser.js
 
-JavaScript library to detect Browser, Engine, OS, CPU, and Device type/model from User-Agent data that can be used either in browser (client-side) or node.js (server-side).
+JavaScript library to detect Browser, Engine, OS, CPU, and Device type/model from User-Agent & Client-Hints data that can be used either in browser (client-side) or node.js (server-side).
 
 * Author    : Faisal Salman <<f@faisalman.com>>
 * Demo      : https://faisalman.github.io/ua-parser-js
@@ -56,25 +56,28 @@ console.log(parser); // {}
 let parserResults = parser.getResult();
 console.log(parserResults);
 /** {
-  "ua": "",
-  "browser": {},
-  "engine": {},
-  "os": {},
-  "device": {},
-  "cpu": {}
+  "ua"      : "",
+  "browser" : {},
+  "engine"  : {},
+  "os"      : {},
+  "device"  : {},
+  "cpu"     : {}
+  
+  // since@1.1 
+  ,"ua_ch"  : {}
 } */
 ```
 
 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@1.1)])`
-    * returns result object `{ ua: '', browser: {}, cpu: {}, device: {}, engine: {}, os: {} }`
+    * returns result object `{ ua: '', browser: {}, cpu: {}, device: {}, engine: {}, os: {} /* added since@1.1: ua_ch: {} */ }`
 
 ## Methods
 
 #### 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:
-`{ ua: '', browser: {}, cpu: {}, device: {}, engine: {}, os: {} }`.
+`{ ua: '', browser: {}, cpu: {}, device: {}, engine: {}, os: {} /* added since@1.1: ua_ch: {} */ }`.
 
  *  `getBrowser()`      - returns the browser name and version.
  *  `getDevice()`       - returns the device model, type, vendor.
@@ -87,7 +90,7 @@ The methods are self explanatory, here's a small overview on all the available m
 ---
 
 * `getResult()`
-    * returns `{ ua: '', browser: UABrowser {}, cpu: UACPU {}, device: UADevice {}, engine: UAEngine {}, os: UAOS {} }`
+    * returns `{ ua: '', browser: {}, cpu: {}, device: {}, engine: {}, os: {} /* added since@1.1: ua_ch: {} */ }`
 
 * `getBrowser()`
     * returns `{ name: '', version: '' }`
@@ -180,7 +183,7 @@ Ubuntu, Unix, VectorLinux, Viera, watchOS, WebOS, Windows [Phone/Mobile], Zenwal
     * set UA string to be parsed
     * returns current instance
 
-#### * is() utility `since@1.1`
+#### * `is()` utility `since@1.1`
 
 ```js
 // Is just a shorthand to check whether specified item has a property with equals value (case-insensitive)
@@ -244,7 +247,7 @@ let engine = uap.getEngine();
 engine.is("Blink");                 // true
 ```
 
-#### * toString() utility `since@1.1`
+#### * `toString()` utility `since@1.1`
 
 ```js
 // Retrieve full-name values as a string
@@ -285,9 +288,33 @@ engine.version;                     // "28.0.1500.95"
 engine.toString();                  // "Blink 28.0.1500.95"
 ```
 
+#### * `withClientHints()` `since@1.1`
+
+Unlike reading user-agent data, accessing client-hints data in browser-environment must be done in an asynchronous way. Worry not, you can chain the UAParser's `get*` method with `withClientHints()` to read the client-hints data as well that will return the updated data as a `Promise`.
+
+```js
+(async function () {  
+    let ua = new UAParser();
+
+    // get browser data from user-agent only :
+    let browser = ua.getBrowser();
+    console.log('Using User-Agent: ', browser);
+
+    // get browser data from client-hints (with user-agent as fallback) :
+    browser = await ua.getBrowser().withClientHints();
+    console.log('Using Client-Hints: ', browser);
+
+    // alternatively :
+    ua.getBrowser().withClientHints().then(function (browser) {
+        console.log('Using Client-Hints: ', browser);
+    });
+})();
+```
+
+
 ## Extending Regex
 
-If you want to detect something that's not currently provided by UAParser.js (eg: bots, specific apps, etc), you can pass a list of regexes to extend internal UAParser.js regexes with your own.
+If you want to detect something that's not currently provided by UAParser.js (eg: `bots`, specific apps, etc), you can pass a list of regexes to extend internal UAParser.js regexes with your own.
 
 * `UAParser([uastring,] extensions [,headers:object(since@1.1)])`
 
@@ -359,6 +386,18 @@ console.log(myParser2.setUA(myUA2).getDevice());  // {vendor: "MyTab", model: "1
             cpu: {
                 architecture: ""
             }
+
+            // added since@1.1:
+            ,ua_ch: {
+                architecture: "",
+                brands: "",
+                bitness: "",
+                fullVersionList: "",
+                mobile: "",
+                model: "",
+                platform: "",
+                platformVersion: ""
+            }
         }
     */
     // Default result depends on current window.navigator.userAgent value