@quotientjs/browser-fingerprint

A lightweight, privacy-conscious browser fingerprinting library for identifying unique browsers.

Features

• Create unique browser fingerprints based on browser characteristics
• High-entropy components for reliable identification
• Handle fingerprint storage and tracking
• Compare fingerprints for similarity
• Configurable collection options
• Supports both localStorage and sessionStorage

Installation

pnpm add @quotientjs/browser-fingerprint

Usage

import BrowserFingerprint from "@quotientjs/browser-fingerprint";

// Create a new fingerprinter
const fingerprinter = new BrowserFingerprint();

// Get the fingerprint (automatically saved to localStorage)
const fingerprint = fingerprinter.get();

console.log("Fingerprint hash:", fingerprint.hash);

Advanced Options

// More options
const fingerprinter = new BrowserFingerprint(
  {
    // Fingerprint options
    excludeComponents: ["canvas", "webgl"], // Exclude privacy-sensitive components
    includeAudio: true,
    includeCanvas: true,
    includeWebGL: true,
    includeFonts: true,
    detectScreenOrientation: true,
  },
  {
    // Storage options
    storageKey: "my_app_fingerprint",
    useSessionStorage: false, // Use localStorage by default
    maxFingerprints: 10,
    similarityThreshold: 0.85,
  },
);

Working with Fingerprints

// Get fingerprint without saving
const fingerprint = fingerprinter.get(false);

// Access all stored fingerprints
const allFingerprints = fingerprinter.getAll();

// Access the storage for more advanced operations
const storage = fingerprinter.getStorage();

// Find the most common fingerprint
const mostFrequent = storage.getMostFrequent();

// Find the most recent fingerprint
const mostRecent = storage.getMostRecent();

// Find a specific fingerprint by hash
const specificFingerprint = storage.findByHash(fingerprint.hash);

// Find a similar fingerprint
const similarFingerprint = storage.findSimilar(fingerprint);

// Clear all fingerprints
fingerprinter.clear();

API Reference

BrowserFingerprint

The main class for fingerprinting operations.

Methods

• get(save = true): Gets or creates a fingerprint
• getAll(): Returns all stored fingerprints
• clear(): Clears all stored fingerprints
• getStorage(): Returns the storage instance

FingerprintStorage

Handles storing and retrieving fingerprints.

Methods

• getAll(): Returns all stored fingerprints
• save(fingerprint, source): Saves a fingerprint
• clear(): Clears all stored fingerprints
• getMostRecent(): Gets the most recently seen fingerprint
• getMostFrequent(): Gets the most frequently seen fingerprint
• findByHash(hash): Finds a fingerprint by hash
• findSimilar(fingerprint): Finds a similar fingerprint

Utility Functions

• createFingerprint(options): Creates a new fingerprint
• calculateSimilarity(fp1, fp2): Calculates similarity between fingerprints
• isSameFingerprint(fp1, fp2, threshold): Determines if two fingerprints match

Development

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build
pnpm build

License

Internal use only.