device-uuid

Fast browser device UUID generation library with comprehensive device detection and advanced fingerprinting capabilities. Written in TypeScript with zero runtime dependencies, supporting both Node.js and browser environments.

Features

• 🚀 Zero runtime dependencies
• 📦 Multiple module formats (ESM, CJS, IIFE)
• 🔍 Comprehensive device detection (OS, browser, platform)
• 📱 Mobile, tablet, and desktop detection
• 🤖 Bot detection (32+ known bot patterns)
• 📺 Smart TV and gaming console detection
• 🎨 Advanced fingerprinting (Canvas, WebGL, Audio, Fonts)
• ⚡ Dual API: Synchronous and Asynchronous
• 🔒 Privacy-by-design (fingerprinting is opt-in)
• 🎨 TypeScript support with full type definitions
• 🌐 Browser and Node.js compatible

Installation

npm install device-uuid

Quick Start

Node.js / Module Bundlers

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

Browser (via <script> tag)

<script src="node_modules/device-uuid/dist/index.browser.min.js"></script>
<script>
  const device = new DeviceUUID.DeviceUUID();
  const uuid = device.get();
  console.log('Device UUID:', uuid);
</script>

API Reference

Synchronous API

Basic device identification using user agent and screen properties.

get(customData?: string): string

Generate a UUID based on device characteristics.

const device = new DeviceUUID();
const uuid = device.get();

parse(source?: string): AgentInfo

Parse user agent string and return device information.

const info = device.parse();
console.log(info.browser); // 'Chrome'
console.log(info.os); // 'Windows 11'
console.log(info.isMobile); // false

getComponents(): Record<string, string | null>

Get individual fingerprint components.

const components = device.getComponents();
console.log(components);
// { userAgent: '...', screen: '1920x1080', language: 'en-US', ... }

Asynchronous API

Advanced fingerprinting with browser characteristics. All methods are opt-in for privacy.

getAsync(options?: FingerprintOptions): Promise<string>

Generate a UUID with advanced fingerprinting methods.

// 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<FingerprintDetails>

Generate UUID and return detailed fingerprint information.

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)

Static Methods

DeviceUUID.isFeatureSupported(feature: FingerprintFeature): boolean

Check if a fingerprinting feature is supported in the current environment.

import { DeviceUUID } from 'device-uuid';

DeviceUUID.isFeatureSupported('canvas');  // true/false
DeviceUUID.isFeatureSupported('webgl');   // true/false
DeviceUUID.isFeatureSupported('audio');   // true/false

Configuration Options

Fingerprint Presets

Presets provide pre-configured options for common use cases:

// 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' });

Custom Options

Fine-grained control over fingerprinting methods:

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

// 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

Basic Device Detection

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}`);

Advanced Fingerprinting

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);
}

Detailed Fingerprint Analysis

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}`);
  }
}

Custom User Agent Parsing

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

Error Handling

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:

Device Type Flags

| 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 |

Browser Information

| 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 |

Operating System

| 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 |

Mobile Platforms

| 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 |

Device Properties

| 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 |

Utility Functions

| 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:

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

License

MIT © Aleksejs Gordejevs and contributors.