Fast browser device uuid generation library.
npm install device-uuidbash
npm install device-uuid
`
Quick Start
$3
`typescript
import { DeviceUUID } from 'device-uuid';
// Basic synchronous UUID (user agent + screen properties)
const device = new DeviceUUID();
const uuid = device.get();
console.log(uuid); // e9dc90ac-d03d-4f01-a7bb-873e14556d8e
// Get device information
const info = device.parse();
console.log(info.browser); // Chrome
console.log(info.os); // Windows 11
console.log(info.isMobile); // false
`
$3
`html
`
$3
`tsx
'use client';
import { useEffect, useState } from 'react';
import { DeviceUUID } from 'device-uuid';
export function DeviceInfo() {
const [uuid, setUuid] = useState(null);
useEffect(() => {
const device = new DeviceUUID();
setUuid(device.get());
}, []);
if (!uuid) return Loading...
;
return Device UUID: {uuid}
;
}
`
API Reference
$3
Basic device identification using user agent and screen properties.
#### get(customData?: string): string
Generate a UUID based on device characteristics.
`typescript
const device = new DeviceUUID();
const uuid = device.get();
`
#### parse(source?: string): AgentInfo
Parse user agent string and return device information.
`typescript
const info = device.parse();
console.log(info.browser); // 'Chrome'
console.log(info.os); // 'Windows 11'
console.log(info.isMobile); // false
`
#### getComponents(): Record
Get individual fingerprint components.
`typescript
const components = device.getComponents();
console.log(components);
// { userAgent: '...', screen: '1920x1080', language: 'en-US', ... }
`
$3
Advanced fingerprinting with browser characteristics. All methods are opt-in for privacy.
#### getAsync(options?: FingerprintOptions): Promise
Generate a UUID with advanced fingerprinting methods.
`typescript
// Enable specific fingerprinting methods
const uuid = await device.getAsync({
canvas: true,
webgl: true,
audio: true,
fonts: true,
timeout: 5000,
});
// Or use a preset
const uuid = await device.getAsync({ preset: 'standard' });
`
#### getDetailedAsync(options?: FingerprintOptions): Promise
Generate UUID and return detailed fingerprint information.
`typescript
const details = await device.getDetailedAsync({ preset: 'standard' });
console.log(details.uuid); // Generated UUID
console.log.details.components); // Individual components
console.log(details.options); // Options used
console.log.details.duration); // Time taken (ms)
`
$3
#### DeviceUUID.isFeatureSupported(feature: FingerprintFeature): boolean
Check if a fingerprinting feature is supported in the current environment.
`typescript
import { DeviceUUID } from 'device-uuid';
DeviceUUID.isFeatureSupported('canvas'); // true/false
DeviceUUID.isFeatureSupported('webgl'); // true/false
DeviceUUID.isFeatureSupported('audio'); // true/false
`
Configuration Options
$3
Presets provide pre-configured options for common use cases:
`typescript
// Minimal - basic device info only (no advanced fingerprinting)
await device.getAsync({ preset: 'minimal' });
// Standard - canvas and WebGL (good uniqueness)
await device.getAsync({ preset: 'standard' });
// Comprehensive - all fingerprinting methods
await device.getAsync({ preset: 'comprehensive' });
`
$3
Fine-grained control over fingerprinting methods:
`typescript
interface FingerprintOptions {
// Fingerprinting methods (all opt-in, default: false)
canvas?: boolean;
webgl?: boolean;
audio?: boolean;
fonts?: boolean | string[]; // true for default list, or custom font list
mediaDevices?: boolean;
networkInfo?: boolean;
timezone?: boolean;
incognitoDetection?: boolean;
// Timeouts
timeout?: number; // Global timeout (default: 5000ms)
methodTimeout?: number; // Per-method timeout (default: 1000ms)
// Preset (overrides individual options)
preset?: 'minimal' | 'standard' | 'comprehensive';
}
`
#### Font Detection
`typescript
// Use default font list
await device.getAsync({ fonts: true });
// Use custom font list
await device.getAsync({
fonts: ['Arial', 'Times New Roman', 'Helvetica', 'Courier New'],
});
`
Usage Examples
$3
`typescript
import { DeviceUUID } from 'device-uuid';
const device = new DeviceUUID();
const info = device.parse();
if (info.isMobile) {
console.log('Mobile device detected');
} else if (info.isTablet) {
console.log('Tablet device detected');
} else {
console.log('Desktop device detected');
}
console.log(Browser: ${info.browser} ${info.version});
console.log(OS: ${info.os});
console.log(Platform: ${info.platform});
`
$3
`typescript
import { DeviceUUID } from 'device-uuid';
const device = new DeviceUUID();
// Check feature support before using
if (DeviceUUID.isFeatureSupported('canvas')) {
const uuid = await device.getAsync({
canvas: true,
webgl: true,
timeout: 5000,
});
console.log('Advanced UUID:', uuid);
}
`
$3
`typescript
import { DeviceUUID } from 'device-uuid';
const device = new DeviceUUID();
const details = await device.getDetailedAsync({
preset: 'standard',
});
console.log('UUID:', details.uuid);
console.log('Components:', details.components);
console.log('Duration:', details.duration, 'ms');
// Check which components were used
for (const [key, value] of Object.entries(details.components)) {
if (value !== null) {
console.log(${key}: ${value});
}
}
`
$3
`typescript
import { DeviceUUID } from 'device-uuid';
const device = new DeviceUUID();
// Parse a custom user agent string
const customUA = 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_2 like Mac OS X) AppleWebKit/605.1.15';
const info = device.parse(customUA);
console.log(info.isiPhone); // true
console.log(info.os); // iOS
console.log(info.browser); // Safari
`
$3
`typescript
import { DeviceUUID } from 'device-uuid';
const device = new DeviceUUID();
try {
const uuid = await device.getAsync({
preset: 'comprehensive',
timeout: 10000,
});
console.log('UUID:', uuid);
} catch (error) {
console.error('Fingerprinting failed:', error);
// Fall back to basic UUID
const basicUuid = device.get();
console.log('Basic UUID:', basicUuid);
}
`
AgentInfo Interface
The parse() method returns an AgentInfo object with the following properties:
$3
| Property | Type | Description |
| --------------- | ----------------- | --------------------- |
| isDesktop | boolean | Desktop computer |
| isMobile | boolean | Mobile phone |
| isTablet | boolean | Tablet device |
| isBot | boolean \| string | Bot/crawler detection |
| isSmartTV | boolean | Smart TV device |
| isTouchScreen | boolean | Touch screen support |
$3
| Property | Type | Description |
| ----------- | ------- | -------------------------------------------------- |
| browser | string | Browser name (Chrome, Firefox, Safari, Edge, etc.) |
| version | string | Browser version |
| isChrome | boolean | Chrome browser |
| isFirefox | boolean | Firefox browser |
| isSafari | boolean | Safari browser |
| isEdge | boolean | Edge browser |
| isOpera | boolean | Opera browser |
| isIE | boolean | Internet Explorer |
$3
| Property | Type | Description |
| ------------ | ------- | --------------------------------- |
| os | string | Operating system name and version |
| isWindows | boolean | Windows OS |
| isMac | boolean | macOS |
| isLinux | boolean | Linux OS |
| isLinux64 | boolean | 64-bit Linux |
| isChromeOS | boolean | Chrome OS |
$3
| Property | Type | Description |
| ----------------- | ------- | ----------------- |
| isAndroid | boolean | Android platform |
| isAndroidTablet | boolean | Android tablet |
| isiPhone | boolean | iPhone |
| isiPad | boolean | iPad |
| isiPod | boolean | iPod touch |
| isSamsung | boolean | Samsung device |
| isBlackberry | boolean | Blackberry device |
$3
| Property | Type | Description |
| ------------ | ---------------- | --------------------------------- |
| platform | string | Platform name |
| language | string | Browser language |
| colorDepth | number | Screen color depth |
| pixelDepth | number | Screen pixel depth |
| resolution | [number, number] | Screen resolution [width, height] |
| cpuCores | number | Number of CPU cores |
| source | string | Original user agent string |
$3
| Method | Description |
| -------------------------------- | --------------------- |
| hashMD5(value: string): string | Generate MD5 hash |
| hashInt(value: string): number | Generate integer hash |
Type Exports
The library exports the following TypeScript types:
`typescript
import type {
DeviceUUIDOptions,
AgentInfo,
FingerprintOptions,
FingerprintDetails,
FingerprintComponent,
FingerprintPreset,
FingerprintFeature,
} from 'device-uuid';
`
Bundle Sizes
| Format | Size |
| ------------------------ | ------------------- |
| ESM | ~31 KB (unminified) |
| CJS | ~31 KB (unminified) |
| Browser (IIFE) | ~34 KB (unminified) |
| Browser (IIFE, minified) | ~19 KB |
Browser Support
- Chrome / Chromium (all versions)
- Firefox (all versions)
- Safari (all versions)
- Edge (Chromium and Legacy)
- Opera (all versions)
- Internet Explorer 11+
Privacy Considerations
This library follows a privacy-by-design approach:
1. Opt-in Default: All advanced fingerprinting methods are disabled by default
2. User Control: Explicit configuration required for each fingerprinting method
3. Timeout Protection: All async operations have configurable timeouts
4. Error Handling: Graceful fallbacks when methods fail or are blocked
5. No Data Exfiltration: All processing happens locally; nothing is sent to external servers
When using advanced fingerprinting:
- Always inform users about data collection
- Obtain appropriate consent when required
- Provide a way to opt-out
- Consider using the minimal` preset for basic identification only