Memulai: Instalasi dan Pemakaian Dasar

ua-parser-js adalah satu paket npm berisi satu kelas utama, UAParser. Memasang paket tidak memerlukan langkah build tambahan: versi terbit sudah membawa sumber CommonJS, sumber ESM, dan berkas dist/ yang siap dimuat. package.json:3-4 package.json:195-205

Memasang paket

Jalankan npm install ua-parser-js. Resolver modul memilih berkas lewat field manifest, bukan lewat satu jalur tunggal.

Field	Nilai	Dipakai oleh
`main`	`src/main/ua-parser.js`	`require()` di Node.js
`module`	`src/main/ua-parser.mjs`	bundler berbasis ESM
`browser`	`dist/ua-parser.pack.js`	bundler yang membaca field `browser`
`types`	`src/main/ua-parser.d.ts`	TypeScript

package.json:195-205

Selain titik masuk utama, paket membuka enam subpath: ua-parser-js/bot-detection, ua-parser-js/browser-detection, ua-parser-js/device-detection, ua-parser-js/enums, ua-parser-js/extensions, dan ua-parser-js/helpers. Masing-masing punya pasangan require/import sendiri beserta deklarasi tipenya. package.json:206-236 Pembahasan subpath ada di Submodule bot-detection, browser-detection, dan device-detection dan Enums dan Konstanta Deteksi.

Berkas yang benar-benar ikut terbit dibatasi ke dist/*.?(m)js, dist/icons, dan src. Manifest juga menunjuk ./script/cli.js sebagai bin; pemakaiannya dibahas di CLI ua-parser-js. package.json:237-243 Paket bergantung pada tiga modul kecil, yaitu detect-europe-js, is-standalone-pwa, dan ua-is-frozen. package.json:257-260

Empat jalur pemuatan

Pilih jalur sesuai runtime. Diagram berikut memetakan tiap jalur ke simbol yang akhirnya tersedia bagi kode pemanggil.

graph LR
  app["Kode pemakai"] -->|require| cjs["src/main/ua-parser.js"]
  app -->|import| mjs["src/main/ua-parser.mjs"]
  app -->|tag skrip| dist["dist/ua-parser.min.js"]
  cjs --> nodeExp["module.exports = UAParser<br/>exports.UAParser"]
  dist --> global["window.UAParser"]
  mjs --> named["export UAParser"]
  style cjs fill:#2d7d46,color:#fff
  style mjs fill:#2d7d46,color:#fff
  style dist fill:#8b5cf6,color:#fff
  style nodeExp fill:#f59e0b,color:#000
  style named fill:#f59e0b,color:#000
  style global fill:#f59e0b,color:#000
%% fig: Empat jalur pemuatan ua-parser-js
%% desc: Setiap entry point mengekspos UAParser dalam bentuk berbeda: module.exports di Node.js, named export di ESM, dan window.UAParser di browser.

Fig. 1: Empat jalur pemuatan ua-parser-jsSetiap entry point mengekspos UAParser dalam bentuk berbeda: module.exports di Node.js, named export di ESM, dan window.UAParser di browser.

Di Node.js, berkas sumber mengisi module.exports dengan fungsi UAParser sekaligus menambahkan properti UAParser, sehingga require() langsung maupun destructuring sama-sama bekerja. Di browser tanpa module loader, nama itu dipasang ke window.UAParser; di lingkungan AMD dipakai define(). src/main/ua-parser.js:1526-1543 Pola pemakaian Node terlihat di test suite, yang mengambil fungsi lewat destructuring. test/unit/main.js:6-7

Versi ESM adalah berkas hasil generate dari sumber CommonJS; header berkasnya menyatakan "DO NOT EDIT THIS FILE!" dan menyebut berkas sumbernya. src/main/ua-parser.mjs:1-3 Skrip script/build-esm.js mengubah require menjadi import dan menutup berkas dengan export {UAParser}. script/build-esm.js:32-43 Hasil akhirnya memang satu named export. src/main/ua-parser.mjs:1519

Untuk tag skrip, gunakan berkas di dist/. Halaman demo internal memuat <script src="./ua-parser.min.js">. dist/ua-parser.html:1 Berkas dist/ dihasilkan uglifyjs oleh skrip build, yang menulis empat varian: ua-parser.min.js, ua-parser.min.mjs, ua-parser.pack.js, dan ua-parser.pack.mjs. script/build-dist.sh:3-9 Rincian prosesnya ada di Build, Test, dan Rilis.

Memanggil `UAParser`

UAParser bisa dipakai sebagai fungsi maupun sebagai constructor. Deklarasi tipe menerima empat bentuk fungsi: UAParser(), UAParser(uastring), UAParser(extensions), dan UAParser(headers), ditambah kombinasi uastring dengan extensions atau headers. src/main/ua-parser.d.ts:62-65 Empat bentuk yang sama berlaku untuk new UAParser(...). src/main/ua-parser.d.ts:100-113 Deklarasi memakai export = UAParser bersama export as namespace UAParser, jadi di TypeScript tipe dan nilai datang dari satu nama yang sama. src/main/ua-parser.d.ts:117-118

Pemilihan arti argumen dilakukan di runtime. Kalau argumen pertama berupa object dan berbentuk extensions — dicek lewat isExtensions — object itu dianggap extensions dan argumen kedua menjadi headers; kalau tidak, object pertama dianggap headers. Kalau argumen pertama string dan argumen kedua bukan extensions, argumen kedua dianggap headers. src/main/ua-parser.js:1422-1438

Headers dinormalisasi lebih dulu: objek Headers diubah menjadi plain object dengan kunci huruf kecil, sedangkan object biasa disalin dengan kunci yang juga di-lowercase dan nilai array digabung memakai ', '. src/main/ua-parser.js:1440-1457

Urutan penentuan user agent: string yang diberikan, lalu headers['user-agent'], lalu navigator.userAgent, dan terakhir string kosong. src/main/ua-parser.js:1459-1466

Pemanggilan tanpa new mengembalikan hasil parse, bukan instance. Kode mengembalikan new UAParser(ua, extensions, headers).getResult() pada kasus itu, dan test menyatakan UAParser(ua) setara dengan new UAParser().setUA(ua).getResult(). src/main/ua-parser.js:1459-1466 test/unit/main.js:24-27

Saat instance dibuat, konstruktor langsung memanggil setUA(userAgent) lalu useExtension(extensions). setUA memotong input dengan UA_MAX_LENGTH yang bernilai 500, sedangkan useExtension menggabungkan regex map tambahan ke map bawaan. src/main/ua-parser.js:22-23 src/main/ua-parser.js:1492-1513

Di browser yang juga memuat jQuery atau Zepto, pustaka ini mengisi $.ua dengan hasil getResult() supaya hasil parse bisa dibaca langsung dari objek $. src/main/ua-parser.js:1545-1553

Membaca hasil per bagian

Setiap method get* dibangun oleh createItemFunc. Untuk satu bagian, fungsi itu membuat UAItem dengan regex map bagian tersebut, memanggil parseUA(), lalu get(). getResult() berbeda: ia membuat UAItem bertipe RESULT, mengisi ua dengan string asli, dan menyalin hasil kelima method bagian ke dalam satu objek. src/main/ua-parser.js:1471-1490

sequenceDiagram
  participant App as Kode pemakai
  participant P as UAParser
  participant I as UAItem
  participant D as IData
  App->>P: new UAParser ua, extensions, headers
  P->>P: normalisasi headers ke lowercase
  P->>P: setUA lalu useExtension
  App->>P: getBrowser
  P->>I: UAItem BROWSER dengan regexMap.browser
  I->>I: parseUA
  I->>D: get
  D-->>App: IBrowser name, version, major, type
  App->>P: getResult
  P->>P: getBrowser lalu getCPU, getDevice, getEngine, getOS
  P-->>App: IResult ua, browser, cpu, device, engine, os
%% fig: Siklus satu instance UAParser
%% desc: Konstruktor menormalkan headers dan menyiapkan regex map, lalu setiap method get* mem-parse satu bagian user agent menjadi IData.

Fig. 2: Siklus satu instance UAParserKonstruktor menormalkan headers dan menyiapkan regex map, lalu setiap method get* mem-parse satu bagian user agent menjadi IData.

Method publik yang tersedia didaftarkan lewat setProps: getBrowser, getCPU, getDevice, getEngine, getOS, getResult, getUA, setUA, dan useExtension. src/main/ua-parser.js:1492-1513

Method	Tipe hasil	Field yang diisi
`getBrowser()`	`IBrowser`	`name`, `version`, `major`, `type`
`getCPU()`	`ICPU`	`architecture`
`getDevice()`	`IDevice`	`type`, `vendor`, `model`
`getEngine()`	`IEngine`	`name`, `version`
`getOS()`	`IOS`	`name`, `version`
`getResult()`	`IResult`	`ua`, `browser`, `cpu`, `device`, `engine`, `os`

src/main/ua-parser.js:1085-1111 src/main/ua-parser.d.ts:21-55

Field yang tidak terdeteksi dibiarkan undefined, bukan diisi nilai default; deklarasi tipe menandai semuanya opsional. src/main/ua-parser.d.ts:21-55 toString() hanya menyusun label dari sebagian field: browser memakai name dan version, device memakai vendor dan model. src/main/ua-parser.js:1085-1111

Method `IData` pada objek hasil

Objek hasil tiap bagian membawa empat method: is(), toString(), withClientHints(), dan withFeatureCheck(). src/main/ua-parser.d.ts:14-19 withClientHints() langsung mem-parse Client Hints yang tersedia di lingkungan non-Chromium, tetapi memanggil getHighEntropyValues dan mengembalikan Promise di browser berbasis Chromium 85+. src/main/ua-parser.js:1128-1150 withFeatureCheck() menjalankan detectFeature() sebelum mengembalikan data. src/main/ua-parser.js:1128-1150

⚠️ IResult dideklarasikan memiliki is() dan toString(), tetapi implementasi hanya memasang keduanya ketika itemType != RESULT. getResult() memakai tipe RESULT, jadi jangan bergantung pada kedua method itu di objek hasil. src/main/ua-parser.js:1152-1175 src/main/ua-parser.d.ts:48-55

Bentuk hasil lengkap, arti tiap field, dan contoh keluaran dibahas di API Utama dan Bentuk Hasil. Perbandingan hasil antar mode ada di Feature Check dan Perbandingan Hasil, sedangkan pembacaan Client Hints ada di Deteksi Client Hints.

Langkah berikutnya

Semua bentuk panggilan di deklarasi tipe mengembalikan IResult, kecuali new UAParser() yang mengembalikan instance. src/main/ua-parser.d.ts:62-65 src/main/ua-parser.d.ts:100-113 Pola itu diverifikasi berkas uji tipe yang memanggil tiap varian dengan expectType. test/static/dts-lint.ts:15-22

Konstanta seperti UAParser.BROWSER dan UAParser.DEVICE juga tersedia sebagai properti statis; daftar lengkapnya ada di Enums dan Konstanta Deteksi. Untuk menambah pola deteksi sendiri, lihat Extensions: Bots, Crawlers, dan Lainnya. Untuk gambaran hubungan antar bagian internal, lanjutkan ke Arsitektur Modul dan Peta Ekspor.