Lightweight Device Detection and UUID Generation Library – Device-UUID

Device-UUID is a TypeScript browser fingerprinting library that generates unique device identifiers and provides device detection capabilities.

It analyzes user agent strings, hardware characteristics, and browser properties to create consistent UUIDs across sessions. Works in both Node.js and browser.

Features:

• Multiple Module Formats: Ships as ESM, CommonJS, and IIFE bundles. Use it in Webpack, Vite, Rollup, or directly via script tags.
• Device Detection: Identifies 40+ browsers, 50+ operating systems, and multiple device types. Includes special detection for Kindle Fire, Samsung devices, and smart TVs.
• Bot Detection: Recognizes major crawlers, including Googlebot, Bingbot, and social media scrapers.
• MD5 Hashing: Built-in MD5 implementation for UUID generation. No crypto library required.
• Custom UUID Generation: Create fingerprints from any combination of device properties. Mix hardware specs, browser data, and screen metrics.

Use Cases:

• Analytics and User Tracking: Track unique visitors across sessions on your website.
• Fraud Detection Systems: Detect when multiple accounts originate from the same device or when users attempt to manipulate voting systems.
• A/B Testing Platforms: Assign users to test groups based on stable device identifiers.
• Session Management: Implement device-based session validation for security-sensitive applications.

How To Use It:

1. Install the Device-UUID package with NPM.

# NPM
$ npm install device-uuid

2. Basic Usage in Node.js:

// Import using ES Modules
import { DeviceUUID } from 'device-uuid';
// Or use CommonJS
const { DeviceUUID } = require('device-uuid');
// Create a new instance
const device = new DeviceUUID();
// Generate a UUID based on device characteristics
// Returns format: xxxxxxxx-xxxx-4xxx-bxxx-xxxxxxxxxxxx
const uuid = device.get();
console.log(uuid); // 5a10e4ab-6181-4e25-b96e-2128070dXXXX
// Parse device information from the current environment
const info = device.parse();
// Access detected browser
console.log(info.browser); // "Chrome"
// Check operating system
console.log(info.os); // "Windows 10"
// Determine device type
console.log(info.isMobile); // false
console.log(info.isDesktop); // true

3. Basic Usage in Browser:

<script src=”/dist/index.browser.min.js”></script>

// Access DeviceUUID through the global namespace
const device = new DeviceUUID.DeviceUUID();
// Generate UUID from browser environment
const uuid = device.get();
console.log('Device UUID:', uuid);
// Parse user agent and get device details
const info = device.parse();
// Log browser information
console.log('Browser:', info.browser); // "Firefox"
console.log('Version:', info.version); // "120.0"
// Check OS
console.log('OS:', info.os); // "macOS Sonoma"
// Verify device type
console.log('Is Mobile:', info.isMobile); // false
console.log('Is Tablet:', info.isTablet); // false

4. Create UUIDs based on specific device properties. This allows you to control which characteristics contribute to the fingerprint.

const device = new DeviceUUID();
// Parse the current device environment
const info = device.parse();
// Build a custom data string from selected properties
// Combine language, platform, OS, hardware, and device flags
const customData = [
  info.language,        // Browser language (e.g., "en-US")
  info.platform,        // Platform name (e.g., "Microsoft Windows")
  info.os,              // Operating system (e.g., "Windows 11")
  info.cpuCores,        // Number of CPU cores (e.g., 8)
  info.isAuthoritative, // Whether detection is authoritative
  info.silkAccelerated, // Silk browser acceleration status
  info.isKindleFire,    // Kindle Fire device detection
  info.isDesktop,       // Desktop computer flag
  info.isMobile,        // Mobile device flag
  info.isTablet,        // Tablet device flag
  info.isWindows,       // Windows OS flag
  info.isLinux,         // Linux OS flag
  info.isLinux64,       // 64-bit Linux flag
  info.isMac,           // macOS flag
  info.isiPad,          // iPad detection
  info.isiPhone,        // iPhone detection
  info.isiPod,          // iPod detection
  info.isSmartTV,       // Smart TV detection
  info.pixelDepth,      // Screen pixel depth (e.g., 24)
  info.isTouchScreen    // Touch screen capability
].join(':');
// Generate MD5 hash from the custom data string
// This creates a UUID that updates only when selected properties change
const customUUID = info.hashMD5(customData);
console.log(customUUID);

5. Device-UUID can analyze any user agent string. This is useful for server-side analysis or testing different device profiles.

const device = new DeviceUUID();
// Define a custom user agent string (iPhone example)
const customUA = 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_2 like Mac OS X) AppleWebKit/605.1.15';
// Parse the custom user agent
const info = device.parse(customUA);
// Check device type
console.log(info.isiPhone); // true
// Verify operating system
console.log(info.os); // "iOS"
// Check if it's a mobile device
console.log(info.isMobile); // true
// Get browser information
console.log(info.browser); // "Safari"

6. Reset Device Information:

const device = new DeviceUUID();
// Parse initial device data
device.parse();
// Reset all properties to default values
// Returns the DeviceUUID instance for method chaining
device.reset();
// The agent is now back to initial state
// All flags are false, all strings are "unknown"

7. The parse() method returns an AgentInfo object. This object contains the following properties.

• version (boolean): Include browser version in UUID generation.
• language (boolean): Include browser language setting.
• platform (boolean): Include platform name (default: true).
• os (boolean): Include operating system name (default: true).
• pixelDepth (boolean): Include screen pixel depth (default: true).
• colorDepth (boolean): Include screen color depth (default: true).
• resolution (boolean): Include screen resolution dimensions.
• isAuthoritative (boolean): Include authoritative detection flag (default: true).
• silkAccelerated (boolean): Include Silk browser acceleration status (default: true).
• isKindleFire (boolean): Include Kindle Fire detection flag (default: true).
• isDesktop (boolean): Include desktop device flag (default: true).
• isMobile (boolean): Include mobile device flag (default: true).
• isTablet (boolean): Include tablet device flag (default: true).
• isWindows (boolean): Include Windows OS flag (default: true).
• isLinux (boolean): Include Linux OS flag (default: true).
• isLinux64 (boolean): Include 64-bit Linux flag (default: true).
• isChromeOS (boolean): Include Chrome OS flag (default: true).
• isMac (boolean): Include macOS flag (default: true).
• isiPad (boolean): Include iPad detection flag (default: true).
• isiPhone (boolean): Include iPhone detection flag (default: true).
• isiPod (boolean): Include iPod detection flag (default: true).
• isAndroid (boolean): Include Android detection flag (default: true).
• isSamsung (boolean): Include Samsung device flag (default: true).
• isSmartTV (boolean): Include smart TV detection flag (default: true).
• isRaspberry (boolean): Include Raspberry Pi detection flag (default: true).
• isBlackberry (boolean): Include BlackBerry detection flag (default: true).
• isTouchScreen (boolean): Include touch screen detection flag (default: true).
• cpuCores (boolean): Include CPU core count.

8. API methods.

// Generate a UUID based on device characteristics
// Optional customData parameter appends additional data to the fingerprint
const uuid = device.get(customData);
// Parse a user agent string and return comprehensive device information
// If no source is provided, uses the current browser's user agent
const info = device.parse(source);
// Reset the device information object to default values
// Returns the DeviceUUID instance for method chaining
device.reset();

9. The AgentInfo object also includes helper functions for hashing.

// Generates an MD5 hash from a string value.
// Useful for creating custom IDs.
info.hashMD5('string-to-hash');
// Generates a simple integer hash from a string value.
// Faster but higher collision risk than MD5.
info.hashInt('string-to-hash');

Alternatives:

• FingerprintJS: A more sophisticated fingerprinting library with advanced entropy sources.
• ClientJS: A simpler client fingerprinting library focused on basic device and browser detection.
• UAParser.js: A user agent string parser without UUID generation capabilities.

FAQs:

Q: Can I use Device-UUID for user authentication?
A: Device-UUID creates fingerprints based on characteristics that can change. Browser updates modify version numbers. Users can change screen resolution or language settings. Operating system upgrades alter the user agent string. Use device UUIDs as a supplementary security signal rather than a primary authentication mechanism.

Q: How do I handle UUID changes when users upgrade their browser?
A: Control which properties contribute to UUID generation through the options object. Exclude the version property when creating the DeviceUUID instance. This keeps the UUID stable across browser updates.

Q: Does Device-UUID work in server-side rendering environments?
A: Device-UUID includes guards for browser-only APIs. The library checks for window and navigator availability before accessing them. When these objects are unavailable, hardware property methods return default values. You can safely import the library in SSR frameworks like Next.js or Nuxt. Pass user agent strings from request headers to the parse() method for server-side analysis.

Q: Is the UUID guaranteed to be unique for every user?
A: No. Browser fingerprinting relies on probability. Two identical laptops (same model, OS, browser, and resolution) will generate the same UUID. We call this a “collision.” It is rare in small datasets but possible.

Q: Does this library use cookies or LocalStorage?
A: No. It is completely stateless. It generates the ID in real-time based on the environment. It stores nothing on the client.