Instalasi dan Penggunaan

Paket ua-parser-js versi 2.0.10 dikirim sebagai dua entry point sumber, yaitu CommonJS dan ESM, ditambah satu build browser dan satu berkas TypeScript definitions. Versi dan lisensi tercatat di header berkas sumber. src/main/ua-parser.js:1-9¹

Entry point yang dideklarasikan paket

package.json memakai field resolusi lama (main, module, browser) sekaligus peta exports untuk resolusi modern.

Sumber nilai tabel: package.json:195-205²

Field files membatasi isi tarball ke dist/*.?(m)js, dist/icons, dan src, sedangkan bin menunjuk ./script/cli.js. package.json:237-243³

Memilih jalur impor

graph TD
    APP["Kode aplikasi"] --> ENV{"Environment pemanggil?"}
    ENV -->|"require"| CJS["src/main/ua-parser.js"]
    ENV -->|"import"| ESM["src/main/ua-parser.mjs"]
    ENV -->|"tag script"| DIST["dist/ua-parser.pack.js"]
    ENV -->|"TypeScript"| DTS["src/main/ua-parser.d.ts"]
    CJS --> CJS_EXP["CommonJS exports"]
    ESM --> ESM_EXP["ESM named export"]
    DIST --> WIN_EXP["window.UAParser"]
    CJS_EXP --> IRESULT["IResult"]
    ESM_EXP --> IRESULT
    WIN_EXP --> IRESULT
    DTS -.-> IRESULT
    style ENV fill:#f59e0b,color:#000
    style DTS fill:#f59e0b,color:#000
    style CJS fill:#336791,color:#fff
    style ESM fill:#336791,color:#fff
    style DIST fill:#336791,color:#fff
    style CJS_EXP fill:#2d7d46,color:#fff
    style ESM_EXP fill:#2d7d46,color:#fff
    style WIN_EXP fill:#2d7d46,color:#fff
    style IRESULT fill:#8b5cf6,color:#fff
%% fig: Jalur impor per environment
%% desc: Node.js memilih varian CommonJS atau ESM, browser memuat build dist yang menempelkan UAParser ke window, dan TypeScript membaca berkas deklarasi.

Di Node.js, src/main/ua-parser.js menetapkan exports = module.exports = UAParser lalu menambahkan exports.UAParser, sehingga baik require('ua-parser-js') maupun bentuk destrukturisasi keduanya mengembalikan konstruktor yang sama. src/main/ua-parser.js:1526-1543⁴

Varian ESM adalah berkas hasil generate dan hanya menutup berkas dengan satu statement export {UAParser}. src/main/ua-parser.mjs:1519⁵

Saat exports tidak tersedia, berkas yang sama mendaftar ke define bila define.amd ada, lalu ke window.UAParser bila environment terdeteksi sebagai window. src/main/ua-parser.js:1526-1543⁴

Memasang paket

npm install ua-parser-js

Nama paket yang dipakai pada contoh resmi adalah ua-parser-js, baik untuk import maupun untuk pemanggilan CLI lewat npx. CHANGELOG.md:20-31⁶

⚠️ Header sumber v2.0.10 menyebut lisensi AGPLv3, berbeda dari lini 1.x. src/main/ua-parser.js:1-9¹

⚠️ Panduan upgrade meminta pembaca membuka CHANGELOG sebelum naik dari v0.7 / v1.0, karena ada perubahan yang breaking. README.md:20-25⁷

Pola pemakaian di Node.js

Bentuk CommonJS yang dipakai unit test:

var { UAParser } = require('ua-parser-js');

Berkas test memuat pola require tersebut sekaligus memastikan bahwa UAParser(ua) tanpa new menghasilkan objek yang sama dengan new UAParser().setUA(ua).getResult(). test/unit/main.js:7-26⁸

Bentuk ESM memakai named import, lalu hasilnya bisa langsung didestrukturisasi per kategori:

import { UAParser } from 'ua-parser-js';

const { cpu, device, engine } = UAParser('Mozilla/5.0 ...');

Pola import dan pemanggilan tanpa new itu diambil dari test ESM. test/unit/es6.mjs:1-24⁹

Pola pemakaian di browser

Bundler yang membaca field browser akan memuat dist/ua-parser.pack.js. package.json:195-205²

Ketika build browser dijalankan tanpa modul CommonJS maupun AMD, UAParser ditempelkan ke window sehingga bisa dipanggil dari tag script. src/main/ua-parser.js:1526-1543⁴

Melewatkan headers

Konstruktor menerima beberapa bentuk argumen: (ua), (ua, headers), (extensions), (extensions, headers), dan (headers). Pembedanya adalah isExtensions, yang memeriksa apakah objek memuat properti browser, cpu, device, engine, atau os. src/main/ua-parser.js:1422-1438¹⁰

Objek Headers dikonversi menjadi objek biasa lebih dulu, lalu seluruh nama header dinormalisasi ke huruf kecil dan nilai berbentuk array digabung menjadi satu string. src/main/ua-parser.js:1440-1457¹¹

Bila tidak ada UA string dan tidak ada header user-agent, parser memakai navigator.userAgent, atau string kosong bila navigator juga tidak tersedia. src/main/ua-parser.js:1459-1466¹²

TypeScript mengekspresikan bentuk argumen yang sama lewat overload UAParser() dan tipe UAParserHeaders, yang menerima Record<string, string | string[] | undefined> atau Headers. src/main/ua-parser.d.ts:60-67¹³

Method publik dan chaining

new UAParser(...) memasang getBrowser, getCPU, getDevice, getEngine, getOS, getResult, getUA, setUA, dan useExtension. setUA serta useExtension mengembalikan this, sehingga pemanggilannya bisa dirantai. src/main/ua-parser.js:1492-1511¹⁴

Rincian tiap method ada di API UAParser. Deklarasi kelas beserta signature method-nya ada di src/main/ua-parser.d.ts:100-113¹⁵, dan export as namespace UAParser memungkinkan pemakaian global dari TypeScript. src/main/ua-parser.d.ts:117-118¹⁶

Submodule yang bisa diimpor terpisah

Setiap submodule punya pasangan require, import, dan types sendiri di peta exports. package.json:206-236¹⁷

ua-parser-js/extensions mengekspor Bots, CLIs, Crawlers, ExtraDevices, Emails, Fetchers, InApps, Libraries, MediaPlayers, dan Vehicles. src/extensions/ua-parser-extensions.js:505-516¹⁸

ua-parser-js/helpers mengekspor getDeviceVendor, isAppleSilicon, isAIBot, isBot, isChromeFamily, isElectron, isFromEU, isFrozenUA, isStandalonePWA, dan getOutlookEdition. src/helpers/ua-parser-helpers.js:100-111¹⁹

Pembahasan tiap submodule ada di Extensions untuk Deteksi Tambahan, Submodule bot-detection, Submodule browser-detection dan device-detection, dan Helpers dan CLI.