[δΈ­ζ–‡ζ–‡ζ‘£](./README_CN.md) | [English](./README.md)
# 🎭 user-agent-generator > πŸš€ High-performance, weighted distribution, batch generation User-Agent spoofing library. Supports multiple browsers, devices, realistic probability distribution, dynamic webkit/safari number concatenation, ultimate anti-crawling protection. Perfect for web scraping, automated testing, proxy pools and more. --- ## ✨ Key Features - βœ… **Smart Weighted Distribution**: Based on real usage data, mainstream versions/systems/kernels have high weights, niche ones have low weights, realistic probability distribution, extremely difficult to detect by frequency analysis - βœ… **Multi-browser/Multi-device**: Supports Chrome / Safari / Firefox, macOS / Windows / iPhone / iPad - βœ… **Dynamic UA Assembly**: webkit/safari numbers and other fields are dynamically sampled, highly realistic browser structure restoration - βœ… **High-performance Batch Generation**: Millisecond-level batch generation, 10000 UAs < 100ms - βœ… **Optional Meta Information**: Can return structured meta information for secondary processing - βœ… **Extensible Data Pool**: All data can be customized and extended, supports weighted distribution - βœ… **Automated Testing**: Full coverage of functionality, performance, and data consistency tests, ensuring robustness --- ## πŸ“¦ Installation ```bash npm i @imaginerlabs/user-agent-generator ``` ## πŸ”§ Quick Start ```js import { generateUserAgent } from '@imaginerlabs/user-agent-generator'; // Generate Chrome + Mac style UA const ua = generateUserAgent({ browser: 'chrome', device: 'mac', }); console.log(ua); // Example output: Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.6367.91 Safari/537.36 // Generate Safari + iPhone style UA const ua2 = generateUserAgent({ browser: 'safari', device: 'iphone', }); console.log(ua2); // Example output: Mozilla/5.0 (iPhone; CPU iPhone OS 17_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1 // Generate Firefox + Windows style UA const ua3 = generateUserAgent({ browser: 'firefox', device: 'windows', }); console.log(ua3); // Example output: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:126.0) Gecko/20100101 Firefox/126.0 ``` ## βœ… Batch Generation Example ```js import { generateUserAgent } from '@imaginerlabs/user-agent-generator'; // Generate 3 Chrome + Mac style UAs in batch const uas = generateUserAgent({ browser: 'chrome', device: 'mac', count: 3, }); console.log(uas); // Example output: // [ // "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.6367.91 Safari/537.36", // "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.6367.92 Safari/537.36", // "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.6367.93 Safari/537.36" // ] ``` ## βœ… Generation with Meta Information Example ```js import { generateUserAgent } from '@imaginerlabs/user-agent-generator'; // Generate Chrome + Mac UA with meta information const result = generateUserAgent({ browser: 'chrome', device: 'mac', withMeta: true, }); console.log(result); // Example output: // { // "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.6367.91 Safari/537.36", // "meta": { // "browser": { "name": "chrome", "version": "124.0.6367.91" }, // "os": { "name": "macos", "version": "14.4" }, // "device": "desktop" // } // } ``` ## 🧰 API Parameters | Parameter | Type | Required | Default | Description | | ---------- | ------------------------------------------------ | -------- | ------- | ----------------------------------------------- | | `browser` | `'chrome'` ｜ `'safari'` ｜ `'firefox'` | No | Random | Specify browser type | | `device` | `'mac'` ｜ `'windows'` ｜ `'iphone'` ｜ `'ipad'` | No | Random | Specify device type | | `count` | `number` | No | `1` | Number of UAs to generate | | `withMeta` | `boolean` | No | `false` | Whether to return version numbers and meta info | ## πŸ”„ Return Types | Scenario | Return Type | Description | | ----------------------- | --------------------- | ----------------------------------------- | | Single UA, no meta | `string` | Returns UA string directly | | Single UA, with meta | `UserAgentWithMeta` | Returns object with ua and meta fields | | Multiple UAs, no meta | `string[]` | Returns array of UA strings | | Multiple UAs, with meta | `UserAgentWithMeta[]` | Returns array of objects with ua and meta | | count=0 | `[]` | Returns empty array | ### UserAgentWithMeta Structure ```typescript interface UserAgentWithMeta { ua: string; // User Agent string meta: { browser: { name: BrowserType; // 'chrome' | 'safari' | 'firefox' version: string; // Browser version number }; os: { name: OSType; // 'macos' | 'windows' | 'ios' | 'ipados' version: string; // Operating system version number }; device: 'desktop' | 'mobile' | 'tablet'; // Device type }; } ``` ## πŸ” Supported Version Ranges & Distribution | Category | Name | Version Range | Distribution Description | | ---------------- | -------------- | ----------------- | ------------------------------------------------------------------------------------- | | Browser | Chrome | `94 ~ 124` | Mainstream high weight (124 weight 25, 123 weight 20), niche low weight (94 weight 1) | | | Safari | `13 ~ 17` | Mainstream high weight, niche low weight | | | Firefox | `88 ~ 126` | Mainstream high weight, niche low weight | | Operating System | macOS | `10.15 ~ 14.4` | Mainstream high weight, niche low weight | | | Windows | `Windows 7 ~ 11` | Mainstream high weight, niche low weight | | | iOS (iPhone) | `13 ~ 17` | Mainstream high weight, niche low weight | | | iPadOS | `13 ~ 17` | Mainstream high weight, niche low weight | | UA Details | WebKit Version | `537.34 ~ 537.36` | Dynamic sub-version sampling, highly realistic browser restoration | | | Safari Version | `537.34 ~ 537.36` | Dynamic sub-version sampling, highly realistic browser restoration | ## πŸ“ Project Structure ``` user-agent-generator/ β”œβ”€β”€ /data/ # Various version information data files (weighted distribution, extensible) β”‚ β”œβ”€β”€ chrome.json # Chrome version data (with weights) β”‚ β”œβ”€β”€ safari.json # Safari version data (with weights) β”‚ β”œβ”€β”€ firefox.json # Firefox version data (with weights) β”‚ β”œβ”€β”€ macos.json # macOS version data (with weights) β”‚ β”œβ”€β”€ windows.json # Windows version data (with weights) β”‚ β”œβ”€β”€ ios.json # iOS version data (with weights) β”‚ └── ipad.json # iPadOS version data (with weights) β”œβ”€β”€ /src/ β”‚ β”œβ”€β”€ index.ts # Main entry module β”‚ β”œβ”€β”€ generator.ts # UA construction logic (weighted distribution, dynamic assembly) β”‚ β”œβ”€β”€ metaBuilder.ts # Meta information assembly logic β”‚ β”œβ”€β”€ types.ts # Type definitions β”‚ └── utils.ts # Utility functions β”œβ”€β”€ /test/ β”‚ β”œβ”€β”€ generator.test.ts # Functionality and performance tests (includes 10000 UA generation performance test) β”‚ β”œβ”€β”€ dataConsistency.test.ts # Data consistency tests β”‚ β”œβ”€β”€ weightDistribution.test.ts # Weight distribution tests β”‚ β”œβ”€β”€ weightedRandomEdgeCases.test.ts # Edge case tests β”‚ └── errorHandling.test.ts # Error handling tests β”œβ”€β”€ README.md β”œβ”€β”€ package.json └── tsconfig.json ``` ## 🧠 Typical Use Cases - πŸ•·οΈ Web scraping / Anti-crawling User-Agent pool construction - πŸ€– Automated testing (Selenium / Puppeteer) - πŸ” Security testing, simulated access - πŸ›°οΈ Building proxy servers or middleware - πŸ“Š Data collection and analysis - 🎯 A/B testing and user behavior simulation ## πŸš€ Performance - Single generation of 10000 UAs < 100ms (based on test cases) - Supports high concurrency and batch calls - Uses random number pool optimization for performance, pre-generates 1000 random numbers to avoid frequent Math.random() calls - Data file caching mechanism to avoid repeated file reads ## πŸ›‘οΈ Data Consistency & Robustness - All data/\*.json files have automated tests to ensure data structure and content health - UA structure highly restores real browsers, WebKit/Safari versions dynamically assembled - Weighted distribution mechanism greatly improves anti-detection capability, supports weighted version selection with sub-values - Complete type definitions, supports TypeScript - Edge case handling: count=0 returns empty array, comprehensive error handling mechanism - 5 test suites with full coverage: functionality tests, performance tests, data consistency, weight distribution, error handling ## πŸ“ƒ License MIT License Β© 2025