API Utama dan Bentuk Hasil

UAParser mengembalikan satu objek hasil yang selalu berbentuk sama: satu string ua dan lima sub-objek browser, cpu, device, engine, serta os. Setiap sub-objek membawa protokol IData yang menyediakan is() dan toString(), ditambah dua method lanjutan withClientHints() dan withFeatureCheck() yang mengembalikan PromiseLike<T> | T src/main/ua-parser.d.ts:14-19¹.

Kontrak tipe itu ditulis di berkas deklarasi, sedangkan implementasinya ada di src/main/ua-parser.js. Halaman ini hanya membahas bentuk data dan method publik tingkat atas; detail withClientHints() ada di Deteksi Client Hints, dan withFeatureCheck() di Feature Check dan Perbandingan Hasil.

Bentuk IResult

IResult mewarisi IData<IResult>, lalu menambahkan ua: string dan lima properti sub-objek. Setiap sub-objek punya tipe sendiri: IBrowser dengan name, version, major, type; ICPU dengan architecture; IDevice dengan type, vendor, model; IEngine dan IOS dengan name serta version src/main/ua-parser.d.ts:21-46² src/main/ua-parser.d.ts:48-55³.

erDiagram
    IRESULT ||--|| IBROWSER : browser
    IRESULT ||--|| ICPU : cpu
    IRESULT ||--|| IDEVICE : device
    IRESULT ||--|| IENGINE : engine
    IRESULT ||--|| IOS : os
    IRESULT {
        string ua
    }
    IBROWSER {
        string name
        string version
        string major
        string type
    }
    ICPU {
        string architecture
    }
    IDEVICE {
        string type
        string vendor
        string model
    }
    IENGINE {
        string name
        string version
    }
    IOS {
        string name
        string version
    }
%% fig: Bentuk IResult dan lima sub-objeknya
%% desc: Satu IResult selalu memuat ua plus lima sub-objek IData, masing-masing dengan field yang sudah baku.

Semua field bertanda ? di deklarasi, jadi nilainya boleh undefined. Untuk UA string kosong, getResult() mengembalikan seluruh field undefined dengan ua: '' test/unit/main.js:92-100⁴. Nama field yang benar-benar dipakai saat inisialisasi objek adalah name, version, major, type, architecture, vendor, dan model src/main/ua-parser.js:1085-1111⁵.

Method publik UAParser

Kelas UAParser mengekspos getUA, getBrowser, getCPU, getDevice, getEngine, getOS, dan getResult; setUA serta useExtension mengembalikan UAParser sehingga bisa dirantai src/main/ua-parser.d.ts:105-113⁶.

getResult() tidak mem-parse ulang UA. Method itu membuat satu UAItem bertipe RESULT, mengisi ua, lalu menyalin hasil this.getBrowser(), this.getCPU(), this.getDevice(), this.getEngine(), dan this.getOS() ke dalamnya src/main/ua-parser.js:1471-1490⁷. Karena itu memanggil satu getter lebih murah daripada memanggil getResult() saat hanya satu field dibutuhkan.

graph LR
    ctor["new UAParser(ua)"] --> setua["setUA"]
    setua --> getres["getResult"]
    getres --> getters["getBrowser / getCPU / getDevice / getEngine / getOS"]
    getters --> result["IResult"]
    ext["useExtension"] --> rgx["regexMap"]
    rgx --> getters
    style setua fill:#f59e0b,color:#000
    style ext fill:#f59e0b,color:#000
    style getres fill:#8b5cf6,color:#fff
    style result fill:#2d7d46,color:#fff
%% fig: Alur method publik UAParser
%% desc: setUA dan useExtension hanya mengubah state instance, sedangkan getResult menyusun IResult dari lima getter.

setUA dan useExtension

Kedelapan method publik dipasang lewat setProps pada instance, dan constructor langsung memanggil .setUA(userAgent).useExtension(extensions) di akhir src/main/ua-parser.js:1493-1511⁸.

setUA hanya menerima string. Nilai non-string diabaikan, dan string yang masuk dirapikan lalu dipotong sepanjang UA_MAX_LENGTH, yaitu 500 karakter src/main/ua-parser.js:22-23⁹ src/main/ua-parser.js:1493-1511⁸. Artinya UA yang lebih panjang dari batas itu dipotong diam-diam, bukan ditolak.

useExtension memanggil extend(regexMap, exts) sehingga regex tambahan digabungkan ke map yang sedang aktif. Pemanggilan berantai memakai input terakhir sebagai pemenang: setUA('MyBrowzer').useExtension(ext1).useExtension(ext2) menghasilkan name: 'Bar' dari ext2 test/unit/main.js:134-159¹⁰. Seluk-beluk bentuk UAParserExt dibahas di Extensions: Bots, Crawlers, dan Lainnya.

⚠️ setUA dan useExtension mengubah instance yang sama. Keduanya mengembalikan this, jadi hasil getResult() yang sudah tersimpan sebelumnya tidak ikut berubah.

Selain dipanggil dengan new, UAParser juga bisa dipanggil sebagai fungsi. Empat overload deklarasinya mengembalikan IResult langsung, sehingga UAParser(ua) setara dengan new UAParser(ua).getResult() src/main/ua-parser.d.ts:61-65¹¹. Pembahasan bentuk pemanggilan itu ada di Memulai: Instalasi dan Pemakaian Dasar.

is() pada sub-objek

is() membandingkan argumennya dengan setiap properti objek hasil, tanpa membedakan huruf besar-kecil. Properti di daftar isIgnore dilewati: version dan major untuk browser, serta version untuk engine dan os. Dua sufiks juga dibuang sebelum perbandingan lewat isIgnoreRgx: / ?browser$/i untuk browser dan / ?os$/i untuk os src/main/ua-parser.js:1085-1111⁵ src/main/ua-parser.js:1152-1175¹².

Efeknya terlihat pada test: getBrowser().is('IEMobile') bernilai true, tetapi is('11.0') bernilai false karena version diabaikan; is('IEMobile Browser') tetap true karena sufiks Browser dibuang. getOS().is('Windows Phone OS') juga true, sementara getOS().is('Windows Mobile') false test/unit/main.js:275-311¹³.

Bila argumennya undefined, is() mengembalikan true ketika ada setidaknya satu properti yang nilainya undefined. Karena itu getDevice().is(undefined) bernilai true untuk UA kosong, sementara getDevice().is('undefined') bernilai false karena string 'undefined' tidak sama dengan nilai undefined test/unit/main.js:329-337¹⁴.

⚠️ Protokol is dipasang pada item selain RESULT src/main/ua-parser.js:1152-1175¹². Deklarasi tipe mewariskan is ke IResult lewat IData, tetapi pemakaian yang diuji adalah pada sub-objek, misalnya getResult().device.is('Nokia') test/unit/main.js:275-311¹³.

toString()

toString() menggabungkan beberapa properti dengan satu spasi. Properti yang dipakai per tipe adalah name + version untuk browser, engine, dan os; architecture untuk cpu; serta vendor + model untuk device. Properti yang undefined dilewati. Bila tidak ada satu pun yang terisi, method ini mengembalikan string 'undefined', bukan string kosong src/main/ua-parser.js:1085-1111⁵ src/main/ua-parser.js:1152-1175¹².

Contoh keluaran yang diuji: "IEMobile 11.0", "arm", "Nokia Lumia 635", "Trident 7.0", dan "Windows Phone 8.1" test/unit/main.js:354-378¹⁵. UA yang tidak menghasilkan apa pun membuat browser.toString() bernilai "undefined" test/unit/main.js:459-463¹⁶.

Bentuk promise dari IData

Selain method di atas, setiap objek hasil punya then(). Method itu menyalin semua properti ke objek baru, lalu memasang ulang is, toString, withClientHints, dan withFeatureCheck pada prototipe objek tersebut src/main/ua-parser.js:1177-1195¹⁷. Ini yang membuat hasil withClientHints() bisa dipakai baik dengan await maupun tanpa await; urutan pemakaiannya dijelaskan di Deteksi Client Hints.

Nilai type pada browser, device, dan cpu berasal dari enum, bukan string bebas. Daftar lengkap nilainya ada di Enums dan Konstanta Deteksi.