中文文档 | English

🎭 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

npm i @imaginerlabs/user-agent-generator

🔧 Quick Start

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

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

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

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