Browser Fingerprinting Library

A powerful, privacy-focused browser fingerprinting library that generates unique identifiers based on browser and device characteristics. Perfect for fraud prevention, analytics, and user identification without cookies.

Features

• Comprehensive Data Collection: Gathers 15+ unique browser and device attributes
• Privacy-Focused: No external dependencies or data transmission
• High Performance: Optimized async operations with minimal impact
• Canvas Fingerprinting: Advanced canvas-based fingerprinting technique
• Cross-Browser Support: Works on all modern browsers
• Device Detection: Mobile, tablet, and desktop identification
• TypeScript Support: Full type safety and IntelliSense
• Flexible Output: Base64, SHA-256 hash, or raw data formats

Table of Contents

• Installation
• Quick Start
• API Reference
• Data Collected
• Advanced Usage
• Use Cases
• Browser Support
• Privacy & Ethics
• Contributing
• License

Installation

npm install @ahmedelsharkawycs/browser-fingerprinting

yarn add @ahmedelsharkawycs/browser-fingerprinting

pnpm add @ahmedelsharkawycs/browser-fingerprinting

Quick Start

JavaScript (ES6+)

import {
  getBrowserFingerprint,
  normalizeFingerprint,
  getFingerprintBase64,
  getFingerprintHashAsync
} from "@ahmedelsharkawycs/browser-fingerprinting"

// Get complete browser fingerprint
const fingerprint = getBrowserFingerprint()
console.log("Full fingerprint:", fingerprint)

// Get normalized fingerprint for ID generation
const normalized = normalizeFingerprint(fingerprint)
console.log("Normalized:", normalized)

// Generate Base64 ID
const base64Id = getFingerprintBase64(normalized)
console.log("Base64 ID:", base64Id)

// Generate SHA-256 hash ID
const hashId = await getFingerprintHashAsync(normalized)
console.log("Hash ID:", hashId)

TypeScript

import {
  getBrowserFingerprint,
  normalizeFingerprint,
  getFingerprintBase64,
  getFingerprintHashAsync,
  type BrowserFingerprint,
  type NormalizedBrowserFingerprint
} from "@ahmedelsharkawycs/browser-fingerprinting"

async function generateFingerprint(): Promise<string> {
  // Get complete fingerprint with full type safety
  const fingerprint: BrowserFingerprint = getBrowserFingerprint()

  // Normalize for consistent ID generation
  const normalized: NormalizedBrowserFingerprint = normalizeFingerprint(fingerprint)

  // Generate a unique hash-based ID
  const uniqueId: string = await getFingerprintHashAsync(normalized)

  return uniqueId
}

API Reference

Core Functions

getBrowserFingerprint(): BrowserFingerprint

Collects comprehensive browser and device information.

Returns: Complete fingerprint object with all available data points.

normalizeFingerprint(fingerprint: BrowserFingerprint): NormalizedBrowserFingerprint

Normalizes fingerprint data for consistent ID generation across sessions.

Parameters:

• fingerprint: The complete browser fingerprint

Returns: Normalized fingerprint with stable attributes only.

getFingerprintBase64(fingerprint: NormalizedBrowserFingerprint): string

Generates a Base64-encoded unique identifier.

Parameters:

• fingerprint: Normalized fingerprint data
• isNormalized: Whether the input is already normalized (default: true)

Returns: URL-safe Base64 encoded ID.

getFingerprintHashAsync(fingerprint: NormalizedBrowserFingerprint): Promise<string>

Generates a SHA-256 hash-based unique identifier.

Parameters:

• fingerprint: Normalized fingerprint data
• isNormalized: Whether the input is already normalized (default: true)

Returns: Hexadecimal SHA-256 hash string.

Data Collected

Browser Information

• User Agent: Browser and OS identification
• Platform: Operating system details
• Vendor: Browser vendor information
• Language: Primary and available languages
• Plugins: Installed browser plugins
• MIME Types: Supported media types

Hardware & Performance

• Screen Resolution: Display dimensions and pixel density
• Hardware Concurrency: CPU core count
• Device Memory: Available RAM (if supported)
• Touch Support: Touch capabilities and max touch points
• Performance Metrics: Timing benchmarks

Graphics & Media

• Canvas Fingerprint: Rendered canvas signature
• WebGL Information: Graphics card vendor and renderer
• Font Detection: Available system fonts

Network & Storage

• Network Information: Connection type and speed
• Storage Support: Local/session storage and IndexedDB
• Local IP Addresses: WebRTC-based IP detection
• Timezone: User's timezone setting

Browser Quirks Detection

• Browser Type: Chrome, Firefox, Safari, Edge, etc.
• Device Type: Mobile, tablet, or desktop
• Operating System: Windows, macOS, Linux, etc.

Advanced Usage

Custom Fingerprint Processing

import { getBrowserFingerprint, normalizeFingerprint, getFingerprintHashAsync } from "@ahmedelsharkawycs/browser-fingerprinting"

async function createCustomFingerprint() {
  const fingerprint = getBrowserFingerprint()

  // Custom processing for specific use cases
  const customData = {
    id: await getFingerprintHashAsync(normalizeFingerprint(fingerprint)),
    deviceType: fingerprint.quirks.mobile ? "mobile" : fingerprint.quirks.tablet ? "tablet" : "desktop",
    browserFamily: fingerprint.quirks.chrome ? "Chrome" : fingerprint.quirks.firefox ? "Firefox" : fingerprint.quirks.safari ? "Safari" : "Other",
    screenSignature: `${fingerprint.screen.width}x${fingerprint.screen.height}@${fingerprint.screen.devicePixelRatio}x`,
    hasWebGL: fingerprint.webgl.vendor !== "unknown",
    timestamp: fingerprint.currentTimestamp
  }

  return customData
}

Fingerprint Comparison

async function compareFingerprints() {
  const fp1 = getBrowserFingerprint()
  const fp2 = getBrowserFingerprint() // Later session

  const id1 = await getFingerprintHashAsync(normalizeFingerprint(fp1))
  const id2 = await getFingerprintHashAsync(normalizeFingerprint(fp2))

  return id1 === id2 // Same user/device
}

Use Cases

Fraud Prevention

async function detectSuspiciousActivity(userFingerprint: string) {
  const currentFingerprint = await getFingerprintHashAsync(normalizeFingerprint(getBrowserFingerprint()))

  return userFingerprint !== currentFingerprint
}

Analytics & Tracking

async function trackUniqueVisitors() {
  const fingerprint = getBrowserFingerprint()
  const visitorId = getFingerprintBase64(normalizeFingerprint(fingerprint))

  // Send to analytics without personal data
  analytics.track("page_view", { visitor_id: visitorId })
}

Session Management

async function validateSession(storedFingerprintId: string) {
  const currentId = await getFingerprintHashAsync(normalizeFingerprint(getBrowserFingerprint()))

  if (currentId !== storedFingerprintId) {
    // Potential session hijacking
    return false
  }
  return true
}

Browser Support

Note: Some features may have limited availability on older browsers or privacy-focused configurations.

Privacy & Ethics

This library is designed for legitimate use cases such as:

• Fraud prevention and security
• Analytics and user experience improvement
• A/B testing and personalization
• Bot detection and spam prevention

Ethical Guidelines

• Always inform users about data collection
• Provide opt-out mechanisms where required
• Comply with privacy regulations (GDPR, CCPA, etc.)
• Don't use for malicious tracking or profiling
• Respect user privacy settings and preferences

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/AhmedElsharkawyCS/browser-fingerprinting
cd browser-fingerprinting
npm install
npm run build

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support & Contact

• Email: ahmed.sharkawy.sde@gmail.com
• Issues: GitHub Issues
• Feature Requests: GitHub Discussions

Made with ❤️ by Ahmed Sharkawy

⭐ Star this repo if you find it useful!