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) with high accuracy

Browser Information

Get browser name, version, engine, and vendor details

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 and CPU cores information

Device Fingerprinting

Generate unique, stable device identifiers

Canvas Fingerprinting

Advanced fingerprinting using Canvas and WebGL

Localization

Language preferences and timezone information

Hardware Details

Screen resolution, pixel ratio, and CPU cores

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, and more.

typescript

const deviceInfo = await getDeviceInfo();
// Returns:
// {
//   os: { name, version, platform, architecture },
//   browser: { name, version, engine, vendor },
//   device: { deviceId, deviceType, hardwareConcurrency, screen, battery },
//   network: { connectionType, cores },
//   language: { current, types },
//   timezone: string,
//   userAgent: string
// }

getOSInfo()

OSInfo

Detects operating system information.

typescript

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

getBrowserInfo()

BrowserInfo

Detects browser information.

typescript

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

getDeviceId()

Promise<{ deviceId: string }>

Generates or retrieves a stable device identifier.

typescript

const { deviceId } = await getDeviceId();
// Returns a unique, persistent device identifier

generateFingerprint()

Promise<string>

Creates a unique device fingerprint using multiple data points.

typescript

const fingerprint = await generateFingerprint();
// Returns a SHA-256 hash based on device characteristics

getBatteryInfo()

Promise<BatteryInfo>

Gets battery information (mobile devices only).

typescript

const batteryInfo = await getBatteryInfo();
// Returns: { level, charging, chargingTime }
// level: 0-100 (percentage), charging: boolean, chargingTime: seconds or null

🎯 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