Extensions: Bots, Crawlers, dan Lainnya

Modul ua-parser-js/extensions mengumpulkan sepuluh extension siap pakai: Bots, CLIs, Crawlers, ExtraDevices, Emails, Fetchers, InApps, Libraries, MediaPlayers, dan Vehicles. Setiap nama diekspor dengan tipe UAParserExt (src/extensions/ua-parser-extensions.d.ts:7-16¹), yaitu Partial<Record<UAParserProps, RegexMap>> atau array dari bentuk itu (src/main/ua-parser.d.ts:57-59²). Sebuah extension hanyalah objek berisi daftar regex per properti browser, cpu, device, engine, atau os.

Extension diambil dari subpath ua-parser-js/extensions: require menunjuk ke ./src/extensions/ua-parser-extensions.js, import ke berkas .mjs, dan types ke .d.ts (package.json:226-230³). Semua objek dibekukan dengan Object.freeze, misalnya MediaPlayers (src/extensions/ua-parser-extensions.js:400-446⁴). Untuk menambah aturan, susun objek baru; jangan mengubah objek bawaan.

Sepuluh extension bawaan

Cara extend menggabungkan regex

extend(defaultRgx, extensions) membangun mergedRgx baru untuk setiap properti yang ada di defaultRgx (src/main/ua-parser.js:130-145¹⁴). Aturannya ada pada satu baris: mergedRgx[k] = extraRgx[k] && extraRgx[k].length % 2 === 0 ? extraRgx[k].concat(defaultRgx[k]) : defaultRgx[k] (src/main/ua-parser.js:142¹⁵). Artinya daftar regex milik extension hanya dipakai bila panjangnya genap, dan selalu diletakkan di depan regex bawaan.

Karena berada di depan, regex extension diuji lebih dulu dan rgxMapper berhenti pada kecocokan pertama (src/main/ua-parser.js:218-236¹⁶). Urutan ini yang membuat Crawlers bisa mengalahkan aturan browser bawaan untuk UA yang sama.

graph TD
    A["Sepuluh extension bawaan<br/>Bots · CLIs · Crawlers · ..."] --> B["UAParser(ua, exts)"]
    B --> C["useExtension(exts)"]
    C --> D["extend(defaultRgx, extensions)"]
    D --> E{"isExtensions: array?"}
    E -->|"array"| F["flatten: ext[i][j].concat(extraRgx[j])<br/>extension terakhir paling depan"]
    E -->|"objek"| G["dipakai langsung"]
    F --> H["mergedRgx[k] = ext[k].concat(defaultRgx[k])<br/>hanya jika panjang genap"]
    G --> H
    H --> I["regexMap: browser · cpu · device · engine · os"]
    I --> J["UAItem.parseUA → rgxMapper<br/>berhenti pada kecocokan pertama"]
    J --> K["browser.type: crawler · fetcher · inapp · ..."]
    style A fill:#f59e0b,color:#000
    style D fill:#f59e0b,color:#000
    style H fill:#f59e0b,color:#000
    style I fill:#8b5cf6,color:#fff
    style K fill:#2d7d46,color:#fff
%% fig: Jalur merge extension ke regexMap
%% desc: Extension digabung ke regexMap oleh extend, regex extension ditempatkan di depan regex bawaan, lalu dipakai rgxMapper saat parse.

Bentuk masukan menentukan cara merge. isExtensions menganggap sebuah objek sebagai satu extension bila properti pertamanya bernama browser, cpu, device, engine, atau os (src/main/ua-parser.js:162-166¹⁷). Jika tidak — misalnya array extension — extend meratakan tiap properti dengan concat, sehingga extension yang berada paling akhir dalam array menempati posisi paling depan (src/main/ua-parser.js:133-140¹⁸).

useExtension menjalankan merge ini lalu mengembalikan this, jadi pemanggilannya bisa dirantai (src/main/ua-parser.js:1505-1511¹⁹). Constructor sudah memanggilnya dengan argumen extensions, dan overload menerima (uastring, extensions, headers) atau (extensions, headers) (src/main/ua-parser.d.ts:100-113²⁰).

⚠️ Daftar regex dengan panjang ganjil tidak memunculkan error: extend diam-diam memakai defaultRgx[k] (src/main/ua-parser.js:142¹⁵). Selalu kirim pasangan [regexes, props] secara lengkap, kalau tidak extension untuk properti itu tidak berefek sama sekali. Karena posisinya di depan, regex kustom juga bisa mengalahkan deteksi bawaan untuk UA yang sama.

Bots: gabungan empat extension

Bots tidak menambahkan regex baru. Definisinya hanya menyebar (...) daftar browser milik CLIs, Fetchers, Crawlers, dan Libraries, lalu menyalin os dari Fetchers (src/extensions/ua-parser-extensions.js:493-503⁵). Karena itu Bots mengisi browser.type dengan cli, fetcher, crawler, atau library (src/extensions/ua-parser-extensions.js:10-23²¹).

graph TD
    Bots["Bots"] --> CLIs["CLIs<br/>type: cli"]
    Bots --> Crawlers["Crawlers<br/>type: crawler"]
    Bots --> Fetchers["Fetchers<br/>type: fetcher"]
    Bots --> Libraries["Libraries<br/>type: library"]
    Fetchers --> Os["Bots.os ← Fetchers.os"]
    style Bots fill:#f59e0b,color:#000
    style Os fill:#2d7d46,color:#fff
%% fig: Komposisi objek Bots
%% desc: Bots menyebar empat daftar browser milik CLIs, Crawlers, Fetchers, dan Libraries, serta mewarisi daftar os dari Fetchers.

Bots tidak memuat Emails, InApps, MediaPlayers, ExtraDevices, maupun Vehicles (src/extensions/ua-parser-extensions.js:493-503⁵). Untuk cakupan seluas itu, gabungkan sendiri lewat array UAParserExt. Modul bot-detection memakai Bots, Crawlers, dan Fetchers dari berkas ini (src/bot-detection/bot-detection.js:11-30²²); pembahasannya ada di Submodule bot-detection, browser-detection, dan device-detection.

Menyusun UAParserExt kustom

Aturan yang berlaku untuk extension buatan sendiri:

• Setiap properti berisi array berselang-seling: elemen indeks genap adalah array RegExp, elemen indeks ganjil adalah array properti hasil (src/main/ua-parser.js:227-236²³).
• Nama properti ditulis sebagai string: name, version, vendor, model, type (src/extensions/ua-parser-extensions.js:10-23²¹).
• Nilai tetap ditulis sebagai pasangan, misalnya [TYPE, 'crawler'] (src/extensions/ua-parser-extensions.js:141-142⁷), dan nama literal memakai bentuk yang sama seperti [[NAME, 'ChatGPT']] (src/extensions/ua-parser-extensions.js:365-366²⁴).
• Fungsi mapper dipakai untuk menormalkan hasil, misalnya [[NAME, normalizeEmailName], VERSION, [TYPE, EMAIL]] (src/extensions/ua-parser-extensions.js:291-295²⁵).
• Bentuk [NAME, /\/.+;/ig, ''] memotong bagian string dengan regex (src/extensions/ua-parser-extensions.js:150-154²⁶).

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

// satu properti, pasangan [regexes, props] dengan panjang genap
const MyDevices = {
    device : [
        [/(acme) (tab[\w]+)/i], ['vendor', 'model', ['type', 'tablet']]
    ]
};

const parser = new UAParser('Mozilla/5.0 (Linux) Acme TabX10', MyDevices);
parser.getDevice();                        // vendor/model/type dari properti yang dideklarasikan
parser.useExtension(MyDevices);            // bisa ditambahkan setelah konstruksi

Properti hasil diisi berurutan dari grup tangkapan regex: pasangan [nama, nilai] menulis nilai tetap, sedangkan [nama, fungsi] menulis hasil fungsi tersebut (src/main/ua-parser.js:238-250²⁷). Nilai type yang dipakai kesepuluh extension di atas sama dengan BrowserType pada modul enums (src/enums/ua-parser-enums.js:186-194²⁸), dan rinciannya ada di Enums dan Konstanta Deteksi. Mekanisme rgxMapper sendiri dibahas di Pipeline Deteksi Regex dan String Map.