Initial work for docs using VitePress

2025-11-18 15:50:36 +03:00 · 2023-04-09 22:04:18 +07:00
parent 38a6b53883
commit 9170c67964
139 changed files with 13258 additions and 29 deletions
--- a/docs/v2/intro/extending-regex.md
+++ b/docs/v2/intro/extending-regex.md
@@ -0,0 +1,59 @@
+# Extending Regex
+
+## Write Your Own Extension
+
+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 extends internal UAParser.js regexes with your own.
+
+- `UAParser([uastring:string,] extensions:object [,headers:object])`
+
+```js
+// Example:
+const myOwnListOfBrowsers = [
+    [/(mybrowser)\/([\w\.]+)/i], [UAParser.BROWSER.NAME, UAParser.BROWSER.VERSION, ['type', 'bot']]
+];
+
+const myUA = 'Mozilla/5.0 MyBrowser/1.3';
+
+const myParser = new UAParser({ browser: myOwnListOfBrowsers });
+
+console.log(myParser.setUA(myUA).getBrowser());  // {name: "MyBrowser", version: "1.3", major: "1", type : "bot"}
+console.log(myParser.getBrowser().is('bot'));    // true
+```
+
+```js
+// Another example:
+const myOwnListOfDevices = [
+    [/(mytab) ([\w ]+)/i], [UAParser.DEVICE.VENDOR, UAParser.DEVICE.MODEL, [UAParser.DEVICE.TYPE, UAParser.DEVICE.TABLET]],
+    [/(myphone)/i], [UAParser.DEVICE.VENDOR, [UAParser.DEVICE.TYPE, UAParser.DEVICE.MOBILE]]
+];
+
+const myUA2 = 'Mozilla/5.0 MyTab 14 Pro Max';
+
+const myParser2 = new UAParser({
+    browser: myOwnListOfBrowsers,
+    device: myOwnListOfDevices
+});
+
+console.log(myParser2.setUA(myUA2).getDevice());  // {vendor: "MyTab", model: "14 Pro Max", type: "tablet"}
+```
+
+::: info
+When custom regexes passed into `UAParser` constructor, they will be ordered **before** internal regexes, thus when the parser runs they will get checked first.
+:::
+
+## Use Predefined Extensions Submodule
+
+Some basic extensions (although not very complete at the moment) can also be found under [`ua-parser-js/extensions`↗](/api/submodules/extensions) submodule.
+
+```js
+// Usage example
+import { UAParser } from 'ua-parser-js';
+import { Emails } from 'ua-parser-js/extensions';
+
+const ua = 'Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.13.0';
+const browser = new UAParser(Emails)
+                    .setUA(ua)
+                    .getBrowser();
+
+console.log(browser.toString()); // Thunderbird 78.13.0
+```
--- a/docs/v2/intro/quick-start/quick-start.md
+++ b/docs/v2/intro/quick-start/quick-start.md
@@ -0,0 +1,9 @@
+# Quick Start
+
+Choose your ~~fighter~~ development strategy:
+
+- [HTML ↗](/intro/quick-start/using-html)
+- [Node.js ↗](/intro/quick-start/using-node-js)
+- [ES Modules ↗](/intro/quick-start/using-es-modules)
+- [TypeScript ↗](/intro/quick-start/using-typescript)
+- [jQuery ↗](/intro/quick-start/using-jquery)
--- a/docs/v2/intro/quick-start/using-es-modules.md
+++ b/docs/v2/intro/quick-start/using-es-modules.md
@@ -0,0 +1,18 @@
+# Using ES Modules
+
+```sh
+$ npm install ua-parser-js
+```
+
+## Code Example
+
+```js
+import { UAParser } from 'ua-parser-js';
+
+const { browser, cpu, device } = UAParser('Mozilla/5.0 (X11; U; Linux armv7l; en-GB; rv:1.9.2a1pre) Gecko/20090928 Firefox/3.5 Maemo Browser 1.4.1.22 RX-51 N900');
+
+console.log(browser.name);          // Maemo Browser
+console.log(cpu.is('arm'));         // true
+console.log(device.is('mobile'));   // true
+console.log(device.model);          // N900
+```
--- a/docs/v2/intro/quick-start/using-html.md
+++ b/docs/v2/intro/quick-start/using-html.md
@@ -0,0 +1,78 @@
+# Using HTML
+---
+- Download minified file locally from [GitHub ↗](https://github.com/faisalman/ua-parser-js/blob/master/dist/ua-parser.pack.js)
+- Or use CDN for extra cache performance
+    - [jsDelivr ↗](https://cdn.jsdelivr.net/npm/ua-parser-js/src/ua-parser.min.js)
+    - [cdnjs ↗](https://cdnjs.com/libraries/UAParser.js)
+
+## Code Example
+
+```html
+<!doctype html>
+<html>
+<head>
+<script src="ua-parser.min.js"></script>
+<script>
+
+    var uap = new UAParser();
+    console.log(uap.getResult());
+    /*
+        /// This will print an object structured like this:
+        {
+            ua: "",
+            browser: {
+                name: "",
+                version: "",
+                major: ""
+            },
+            engine: {
+                name: "",
+                version: ""
+            },
+            os: {
+                name: "",
+                version: ""
+            },
+            device: {
+                model: "",
+                type: "",
+                vendor: ""
+            },
+            cpu: {
+                architecture: ""
+            }
+        }
+    */
+    // Default result depends on current window.navigator.userAgent value
+
+    // Now let's try a custom user-agent string as an example
+    var uastring1 = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/535.2 (KHTML, like Gecko) Ubuntu/11.10 Chromium/15.0.874.106 Chrome/15.0.874.106 Safari/535.2";
+    uap.setUA(uastring1);
+    var result = uap.getResult();
+    // You can also use UAParser constructor directly without having to create an instance:
+    // var ua = UAParser(uastring1);
+
+    console.log(result.browser);        // {name: "Chromium", version: "15.0.874.106"}
+    console.log(result.device);         // {model: undefined, type: undefined, vendor: undefined}
+    console.log(result.os);             // {name: "Ubuntu", version: "11.10"}
+    console.log(result.os.version);     // "11.10"
+    console.log(result.engine.name);    // "WebKit"
+    console.log(result.cpu.architecture);   // "amd64"
+
+    // Do some other tests
+    var uastring2 = "Mozilla/5.0 (compatible; Konqueror/4.1; OpenBSD) KHTML/4.1.4 (like Gecko)";
+    console.log(uap.setUA(uastring2).getBrowser().name); // "Konqueror"
+    console.log(uap.getOS());                            // {name: "OpenBSD", version: undefined}
+    console.log(uap.getEngine());                        // {name: "KHTML", version: "4.1.4"}
+
+    var uastring3 = 'Mozilla/5.0 (PlayBook; U; RIM Tablet OS 1.0.0; en-US) AppleWebKit/534.11 (KHTML, like Gecko) Version/7.1.0.7 Safari/534.11';
+    console.log(uap.setUA(uastring3).getDevice().model); // "PlayBook"
+    console.log(uap.getOS())                             // {name: "RIM Tablet OS", version: "1.0.0"}
+    console.log(uap.getBrowser().name);                  // "Safari"
+
+</script>
+</head>
+<body>
+</body>
+</html>
+```
--- a/docs/v2/intro/quick-start/using-jquery.md
+++ b/docs/v2/intro/quick-start/using-jquery.md
@@ -0,0 +1,43 @@
+# Using jQuery/Zepto ($.ua)
+
+Although written in vanilla js, this library will automatically detect if jQuery/Zepto is present and create `$.ua` object (with values based on its User-Agent) along with `window.UAParser` constructor. To get/set user-agent you can use: 
+
+## `$.ua.get():string`
+
+Get user-agent string
+
+## `$.ua.set(ua:string)`
+
+Set user-agent string
+
+## Code Example
+
+```js
+// Say we are in a browser which has default user-agent: 
+// "Mozilla/5.0 (Linux; U; Android 2.3.4; en-us; Sprint APA7373KT Build/GRJ22) AppleWebKit/533.1 (KHTML, like Gecko) Version/4.0"
+
+// Get the details
+console.log($.ua.device);           // {vendor: "HTC", model: "Evo Shift 4G", type: "mobile"}
+console.log($.ua.os);               // {name: "Android", version: "2.3.4"}
+console.log($.ua.os.name);          // "Android"
+console.log($.ua.get());            // "Mozilla/5.0 (Linux; U; Android 2.3.4; en-us; Sprint APA7373KT Build/GRJ22) AppleWebKit/533.1 (KHTML, like Gecko) Version/4.0"
+
+// Now lets try to reset to another custom user-agent
+$.ua.set('Mozilla/5.0 (Linux; U; Android 3.0.1; en-us; Xoom Build/HWI69) AppleWebKit/534.13 (KHTML, like Gecko) Version/4.0 Safari/534.13');
+
+// Test again
+console.log($.ua.browser.name);     // "Safari"
+console.log($.ua.engine.name);      // "Webkit"
+console.log($.ua.device);           // {vendor: "Motorola", model: "Xoom", type: "tablet"}
+console.log($.ua.browser.version);  // "4.0"
+console.log($.ua.browser.major);    // "4"
+
+// Add class to <body> tag
+// <body class="ua-browser-safari ua-devicetype-tablet">
+$('body')
+    .addClass(
+        'ua-browser-' + 
+        $.ua.browser.name + 
+        ' ua-devicetype-' + 
+        $.ua.device.type);
+```
--- a/docs/v2/intro/quick-start/using-node-js.md
+++ b/docs/v2/intro/quick-start/using-node-js.md
@@ -0,0 +1,35 @@
+# Using Node.js
+
+```sh
+$ npm install ua-parser-js
+```
+
+## Code Example
+
+```js
+var http = require('http');
+var uap = require('ua-parser-js');
+
+http.createServer(function (req, res) {
+    // get user-agent header
+    var ua = uap(req.headers['user-agent']);
+
+    /* // BEGIN since@2.0 - you can also pass client-hints data to UAParser
+
+    // note: only works in secure context (https:// or localhost or file://)
+
+    var getHighEntropyValues = 'Sec-CH-UA-Full-Version-List, Sec-CH-UA-Mobile, Sec-CH-UA-Model, Sec-CH-UA-Platform, Sec-CH-UA-Platform-Version, Sec-CH-UA-Arch, Sec-CH-UA-Bitness';
+    res.setHeader('Accept-CH', getHighEntropyValues);
+    res.setHeader('Critical-CH', getHighEntropyValues);
+    
+    var ua = uap(req.headers).withClientHints();
+
+    // END since@2.0 */
+
+    // write the result as response
+    res.end(JSON.stringify(ua, null, '  '));
+})
+.listen(1337, '127.0.0.1');
+
+console.log('Server running at http://127.0.0.1:1337/');
+```
--- a/docs/v2/intro/quick-start/using-typescript.md
+++ b/docs/v2/intro/quick-start/using-typescript.md
@@ -0,0 +1,19 @@
+# Using TypeScript
+
+```sh
+$ npm install --save ua-parser-js
+# Install ua-parser-js
+
+$ npm install --save-dev @types/ua-parser-js
+# Download type definition from DefinitelyTyped repository
+# https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/ua-parser-js
+```
+
+## Code Example
+
+```js
+import { UAParser } from 'ua-parser-js'; 
+
+const parser = new UAParser();
+console.log(parser.getResult());
+```
--- a/docs/v2/intro/why-ua-parser-js.md
+++ b/docs/v2/intro/why-ua-parser-js.md
@@ -0,0 +1,39 @@
+# Why UAParser.js
+
+---
+
+This illustration sums up why:
+
+```js
+// Consider we got this user-agent (yes it's real):
+const ua = `Mozilla/5.0 (Linux; Android 10; STK-LX1 
+Build/HONORSTK-LX1; wv) AppleWebKit/537.36 (KHTML, 
+like Gecko) Version/4.0 Chrome/110.0.5481.153 Mobile 
+Safari/537.36 musical_ly_2022803040 JsSdk/1.0 
+NetType/WIFI Channel/huaweiadsglobal_int 
+AppName/musical_ly app_version/28.3.4 ByteLocale/en 
+ByteFullLocale/en Region/IQ Spark/1.2.7-alpha.8 
+AppVersion/28.3.4 PIA/1.5.11 BytedanceWebview/d8a21c6`;
+
+// what???
+```
+
+Worry not:
+
+```js
+// Just pass it to `UAParser`
+const parser = new UAParser(ua);
+
+// And voila!
+console.log(parser.getBrowser());
+// { name : "TikTok", version : "28.3.4", major : "28" }
+
+console.log(parser.getEngine());
+// { name : "Blink", version : "110.0.5481.153" }
+
+console.log(parser.getDevice());
+// { type : "mobile", vendor : "Huawei", model : "STK-LX1" }
+
+console.log(parser.getOS());
+// { name : "Android", version : "10" }
+```