Ringkasan Proyek

UAParser.js adalah pustaka JavaScript tanpa dependensi yang mendeteksi browser, engine, OS, CPU, dan device dari data User-Agent serta Client Hints. Pustaka ini berjalan di browser maupun Node.js, dan versi pada commit ini adalah 2.0.10 (package.json:1-6¹). README menyebutnya sebagai deteksi User-Agent yang kompak, ramah ES5, dan tanpa dependensi (README.md:10-14²).

Sumber utama pustaka ada di src/main/ua-parser.js. Versi 2.0.10 juga tertulis sebagai LIBVERSION di dalam berkas itu, bersama batas UA_MAX_LENGTH = 500 dan penanda nilai tak dikenal UNKNOWN = '?' (src/main/ua-parser.js:22-32³). Versi ESM di src/main/ua-parser.mjs adalah berkas hasil generate, sehingga perubahan tetap dilakukan pada sumber CommonJS (src/main/ua-parser.mjs:1-3⁴).

Bentuk keluaran

Semua pemanggilan bermuara pada satu objek IResult. Interface TypeScript-nya memuat ua sebagai string, ditambah lima objek: browser, cpu, device, engine, dan os (src/main/ua-parser.d.ts:48-55⁵). Setiap objek item memiliki is(), toString(), withClientHints(), dan withFeatureCheck() di sisi runtime, sementara tipe publiknya mengekspos getBrowser(), getCPU(), getDevice(), getEngine(), getOS(), getResult(), setUA(), dan useExtension() (src/main/ua-parser.d.ts:105-114⁶). Rincian tiap field dibahas di API Utama dan Bentuk Hasil.

Alur UAParser() ke getResult()

Diagram berikut menunjukkan perjalanan satu pemanggilan: argumen masuk ke konstruktor UAParser, headers dinormalkan, kemudian setUA dan useExtension menyiapkan keadaan, dan getResult merakit lima item menjadi satu hasil.

graph TD
    IN["User-Agent string atau headers"] --> CTOR["UAParser(ua, extensions, headers)"]
    CTOR --> NORM["normalisasi nama header ke lowercase"]
    NORM --> SETUA["setUA(userAgent)"]
    SETUA --> EXT["useExtension(extensions)"]
    EXT --> GR["getResult()"]
    GR --> BR["getBrowser()"]
    GR --> CP["getCPU()"]
    GR --> DV["getDevice()"]
    GR --> EN["getEngine()"]
    GR --> OS["getOS()"]
    BR --> RES["IResult: ua, browser, cpu, device, engine, os"]
    CP --> RES
    DV --> RES
    EN --> RES
    OS --> RES
    style CTOR fill:#f59e0b,color:#000
    style NORM fill:#f59e0b,color:#000
    style GR fill:#8b5cf6,color:#fff
    style RES fill:#2d7d46,color:#fff
%% fig: Alur satu pemanggilan UAParser sampai getResult
%% desc: Konstruktor menormalkan headers, menyiapkan User-Agent dan extensions, lalu getResult merakit lima hasil item menjadi satu IResult.

Konstruktor menerima tiga argumen dalam berbagai urutan. Bila argumen pertama berupa objek, ia diperlakukan sebagai extensions atau headers; bila berupa string dan argumen kedua bukan extensions, argumen kedua dianggap headers. Objek Headers diubah menjadi objek biasa lewat forEach, sedangkan header biasa dinormalkan ke huruf kecil dan nilai array digabung dengan ', '. Urutan penentuan User-Agent adalah string yang diberikan, lalu headers['user-agent'], lalu navigator.userAgent, lalu string kosong (src/main/ua-parser.js:1440-1466⁷).

Method publik dipasang lewat satu setProps di akhir konstruktor: getBrowser, getCPU, getDevice, getEngine, getOS, getResult, getUA, setUA, dan useExtension. Rantai ini ditutup dengan .setUA(userAgent).useExtension(extensions) (src/main/ua-parser.js:1493-1511⁸). getResult tidak memanggil parser sekali lagi; ia membuat UAItem bertipe result lalu mengisi browser, cpu, device, engine, dan os dari getter masing-masing sebelum memanggil .get() (src/main/ua-parser.js:1471-1490⁹). Karena itu new UAParser(ua).getResult() dan UAParser(ua) menghasilkan objek yang sama: pemanggilan tanpa new diteruskan ke new UAParser(...).getResult() (src/main/ua-parser.js:1459-1461¹⁰).

Siklus hidup item hasil

Setiap item membawa tiga operasi tambahan di atas IData. withClientHints() memakai navigator.userAgentData.getHighEntropyValues(CH_ALL_VALUES) pada browser Chromium 85+ dan mengembalikan Promise, tetapi mengembalikan objek langsung di Node.js atau browser tanpa Client Hints. withFeatureCheck() memanggil item.detectFeature().get() (src/main/ua-parser.js:1128-1150¹¹). Keduanya dijelaskan lebih jauh di Deteksi Client Hints dan Feature Check dan Perbandingan Hasil.

Peta submodule

Paket mengekspor enam entry point. Setiap submodule tersedia dalam pasangan CommonJS dan ESM beserta definisi TypeScript-nya (package.json:200-236¹²).

Submodule helpers adalah gabungan fungsi lama yang kini juga dipisah ke bot-detection, browser-detection, dan device-detection (CHANGELOG.md:52-76¹⁷). Pembagian ini dibahas di Submodule bot-detection, browser-detection, dan device-detection, sedangkan isi extensions dibahas di Extensions: Bots, Crawlers, dan Lainnya dan konstanta di Enums dan Konstanta Deteksi. Peta ekspor tingkat berkas ada di Arsitektur Modul dan Peta Ekspor.

Kelas UAParser sebagai permukaan API

Selain method instance, kelas membawa properti statis: UAParser.VERSION berisi LIBVERSION, sedangkan BROWSER, CPU, DEVICE, ENGINE, dan OS adalah hasil enumerize atas nama field masing-masing, misalnya DEVICE memuat CONSOLE, MOBILE, SMARTTV, TABLET, WEARABLE, dan EMBEDDED (src/main/ua-parser.js:1516-1520¹⁸). Nama-nama ini yang dipakai untuk membaca hasil tanpa menulis string mentah.

Ekspor menyesuaikan lingkungan. Di Node.js, module.exports diisi UAParser sekaligus exports.UAParser; bila tidak ada exports, pustaka mendaftar lewat define.amd, lalu jatuh ke window.UAParser. Integrasi jQuery/Zepto juga disiapkan lewat $.ua bila objek tersebut tersedia (src/main/ua-parser.js:1527-1543¹⁹).

Lisensi dan kompatibilitas

⚠️ Versi 2.x memakai lisensi copyleft AGPL-3.0-or-later, berbeda dari MIT pada 1.x. Paket juga mendeklarasikan "node": "*" pada engines, sehingga tidak ada batas versi Node.js yang dipaksakan (package.json:281-284²⁰).

Migrasi dari v1 membawa perubahan keluaran yang terlihat langsung pada hasil deteksi: browser "Chrome" menjadi "Mobile Chrome" dan "Firefox" menjadi "Mobile Firefox" pada perangkat mobile, sedangkan "Mac OS" menjadi "macOS" dan "Chromium OS" menjadi "Chrome OS" (CHANGELOG.md:3-16²¹). Langkah pemasangan dan pemakaian dasar ada di Memulai: Instalasi dan Pemakaian Dasar, sedangkan proses build dan rilis dijelaskan di Build, Test, dan Rilis. Untuk pemakaian dari terminal, lihat CLI ua-parser-js, dan untuk mesin pencocokan regex di balik layar, lihat Pipeline Deteksi Regex dan String Map.