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.