v1.0.0MIT License

@marufme/device-key 🔑

A lightweight, comprehensive device detection and fingerprinting library for modern web applications. Get detailed information about user devices, browsers, operating systems, and generate unique device fingerprints.

View on GitHub

✨ Features

Comprehensive device detection and fingerprinting capabilities for modern web applications

Device Detection

Identify device type (Desktop, Mobile, Tablet)

Browser Information

Get browser name, version, engine, and vendor

OS Detection

Detect operating system name, version, platform, and architecture

Battery Status

Monitor battery level, charging status, and charging time

Network Info

Get network connection type, effectiveType, downlink, RTT, and CPU cores

Device Fingerprinting

Generate unique, stable device identifiers

Canvas & WebGL Fingerprinting

Canvas and WebGL helpers used for fingerprints

IP Detection & VPN Bypass

Detect public/real IP, VPN/Proxy, and possible DNS leaks

Localization

Language preferences, timezone, DST, and optional coordinates

Hardware Details

Screen resolution, pixel ratio, and CPU cores

Incognito Detection

Heuristic detection using StorageManager quota

Privacy Aware

Server-side safe with graceful fallbacks

🚀 Installation

Get started with device-key in seconds

Choose your package manager

bash

npm install @marufme/device-key

📖 Quick Start

Start detecting devices in minutes

Basic Usage

typescript

import getDeviceInfo from "@marufme/device-key";

// Get comprehensive device information
const deviceInfo = await getDeviceInfo();
console.log(deviceInfo);

🔧 API Reference

Complete API documentation for all available methods

getDeviceInfo()

Promise<Device>

Returns comprehensive device information including OS, browser, device details, network info, user-agent, location, and incognito status.

typescript

const deviceInfo = await getDeviceInfo();
// Returns:
// {
//   os: { name, version, platform, architecture },
//   browser: { name, version, engine, vendor },
//   device: {
//     deviceId,
//     deviceType,
//     hardwareConcurrency,
//     screen: { width, height, pixelRatio },
//     battery: { level, charging, chargingTime }
//   },
//   network: { connectionType?, effectiveType?, downlink?, rtt?, cores? },
//   location: {
//     timezone: { timezone, offset, dst },
//     language: { current, types, primary },
//     coordinates?: GeolocationCoordinates,
//     ipInfo?: {
//       publicIP,
//       realIP?,
//       isVPN,
//       isProxy,
//       isTor,
//       country?,
//       city?,
//       isp?,
//       confidence
//     }
//   },
//   userAgent: string,
//   incognito: boolean
// }

getOSInfo()

OSInfo

Detects operating system information.

typescript

const osInfo = getOSInfo();
// { name, version, platform, architecture }
// Example: { name: "Windows", version: "10", platform: "Win32", architecture: "64-bit" }

getBrowserInfo()

BrowserInfo

Detects browser information.

typescript

const browserInfo = getBrowserInfo();
// { name, version, engine, vendor }
// Example: { name: "Chrome", version: "120.0.0.0", engine: "Blink", vendor: "Google Inc." }

detectIncognitoMode()

Promise<boolean>

Heuristic detection using StorageManager quota (returns true if incognito/private mode likely).

typescript

const isIncognito = await detectIncognitoMode();

getDeviceInfoBasic()

Promise<DeviceBasicInfo>

Gets basic device information including screen details and battery status.

typescript

const info = await getDeviceInfoBasic();
// {
//   deviceId,
//   deviceType: "Desktop" | "Mobile" | "Tablet",
//   hardwareConcurrency,
//   screen: { width, height, pixelRatio },
//   battery: { level, charging, chargingTime }
// }

getDeviceId()

Promise<{ deviceId: string }>

Generates or retrieves a stable device identifier. On first run in the browser, it generates a fingerprint and stores it in localStorage under a small key. On non-browser environments, returns "server-mode".

typescript

const { deviceId } = await getDeviceId();

getBatteryInfo()

Promise<BatteryInfo>

Gets battery information (where supported).

typescript

const battery = await getBatteryInfo();
// { level: 0-100, charging: boolean, chargingTime: number | null }

getNetworkInfo()

NetworkInfo

Gets network connection information and CPU cores where available.

typescript

const net = getNetworkInfo();
// {
//   connectionType?,
//   effectiveType?,
//   downlink?,
//   rtt?,
//   cores?
// }

getUserAgent()

{ userAgent: string }

Returns the current user agent string.

typescript

const { userAgent } = getUserAgent();

parseUserAgent()

UserAgentInfo

Lightweight UA parsing helpers.

typescript

const ua = parseUserAgent();
// { userAgent, isMobile, isTablet, isDesktop, isBot }

getLocationInfo()

Promise<LocationInfo>

Aggregates timezone, language, and optional geolocation coordinates (if permitted) and IP information.

typescript

const loc = await getLocationInfo();
// {
//   timezone: { timezone, offset, dst },
//   language: { current, types, primary },
//   coordinates?: GeolocationCoordinates,
//   ipInfo?: IPInfo
// }

getTimezoneInfo()

TimezoneInfo

Gets timezone identifier, UTC offset (minutes east of UTC), and DST flag.

typescript

const tz = getTimezoneInfo();
// { timezone, offset, dst }

getLanguageInfo()

LanguageInfo

Gets language preferences.

typescript

const lang = getLanguageInfo();
// { current, types, primary }

getIPInfo()

Promise<IPInfo>

Advanced IP detection with VPN/Proxy insights. Uses WebRTC leak checks, public IP services, and heuristic VPN/Proxy signals.

typescript

const ip = await getIPInfo();
// {
//   publicIP: string,
//   realIP?: string,
//   isVPN: boolean,
//   isProxy: boolean,
//   isTor: boolean,
//   country?: string,
//   city?: string,
//   isp?: string,
//   confidence: number
// }

generateFingerprint()

Promise<string>

Creates a unique device fingerprint using basic info + Canvas + WebGL, hashed with SHA-256.

typescript

const fp = await generateFingerprint();

getCanvasFingerprint()

string

Generates a canvas-based fingerprint string (data URL).

typescript

const canvasFp = getCanvasFingerprint();

getWebGLFingerprint()

string

Generates a WebGL-based fingerprint string (vendor::renderer).

typescript

const webglFp = getWebGLFingerprint();

🎯 Use Cases

Real-world applications for device detection

Analytics

Track device types and capabilities to understand your user base better

User Experience

Adapt UI based on device capabilities for optimal user experience

Security

Device fingerprinting for fraud detection and security monitoring

Performance

Optimize based on device specifications and network conditions

Debugging

Collect device information for troubleshooting and support

A/B Testing

Segment users by device characteristics for targeted testing