device-uuid

Features

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();
 const uuid = device.get();
 console.log('Device UUID:', uuid);
</script>

React

'use client';
import { useEffect, useState } from 'react';
import { DeviceUUID } from 'device-uuid';
export function DeviceInfo() {
 const [uuid, setUuid] = useState<string | null>(null);
 useEffect(() => {
 const device = new DeviceUUID();
 setUuid(device.get());
 }, []);
 if (!uuid) return <p>Loading...</p>;
 return <p>Device UUID: {uuid}</p>;
}

API Reference

Synchronous API

get(customData?: string): string

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

parse(source?: string): AgentInfo

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>

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

Asynchronous API

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

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

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

import { DeviceUUID } from 'device-uuid';
DeviceUUID.isFeatureSupported('canvas'); // true/false
DeviceUUID.isFeatureSupported('webgl'); // true/false
DeviceUUID.isFeatureSupported('audio'); // true/false

Configuration Options

Fingerprint Presets

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

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

Device Type Flags

Browser Information

Operating System

Mobile Platforms

Device Properties

Utility Functions

Type Exports

import type {
 DeviceUUIDOptions,
 AgentInfo,
 FingerprintOptions,
 FingerprintDetails,
 FingerprintComponent,
 FingerprintPreset,
 FingerprintFeature,
} from 'device-uuid';

Bundle Sizes

Browser Support

Privacy Considerations

License