FingerprinterJS

A modern JavaScript library for generating unique and reliable browser fingerprints.

🚀 Features

• Complete fingerprinting: Uses multiple fingerprinting techniques (Canvas, WebGL, Audio, Fonts, etc.)
• TypeScript: Full support with included types
• Modular: Ability to exclude certain collectors
• Compatible: Works in all modern browsers
• Lightweight: Optimized bundle with no dependencies
• Secure: Uses SHA-256 for hashing when available
• Smart Stability: Automatically filters unstable data
• Suspect Analysis: Built-in bot and fraud detection

📦 Installation

npm install fingerprinter-js

🔧 Usage

Basic Usage

import Fingerprint from "fingerprinter-js";

// Simple generation
const result = await Fingerprint.generate();
console.log(result.fingerprint); // "a1b2c3d4e5f6..."
console.log(result.confidence); // 85

Advanced Usage

import { Fingerprint } from "fingerprinter-js";

// With custom options
const fingerprint = new Fingerprint({
  excludeCanvas: true,
  excludeWebGL: true,
  customData: {
    userId: "12345",
    sessionId: "abc-def-ghi", // ⚠️ Will be automatically filtered for stability
    version: "1.0", // ✅ Stable, will be kept
  },
});

// To include unstable data (not recommended)
const unstableFingerprint = new Fingerprint({
  allowUnstableData: true,
  customData: {
    timestamp: Date.now(), // ⚠️ Will make fingerprint unstable
    sessionId: "random-id",
  },
});

const result = await fingerprint.generate();

With Suspect Analysis

// Enable bot/fraud detection
const result = await Fingerprint.generate({
  includeSuspectAnalysis: true,
});

console.log(result.suspectAnalysis);
// {
//   score: 15,           // 0-100 (0=legitimate, 100=very suspicious)
//   riskLevel: 'LOW',    // LOW/MEDIUM/HIGH
//   signals: [...],      // Detected suspicious signals
//   details: {...}       // Analysis details
// }

Available Options

interface FingerprintOptions {
  excludeScreenResolution?: boolean;
  excludeTimezone?: boolean;
  excludeLanguage?: boolean;
  excludeCanvas?: boolean;
  excludeWebGL?: boolean;
  excludeAudio?: boolean;
  excludePlugins?: boolean;
  excludeFonts?: boolean;
  customData?: Record<string, any>;
  allowUnstableData?: boolean; // Allow temporal data (default: false)
  includeSuspectAnalysis?: boolean; // Include suspect analysis (default: false)
}

⚠️ Automatic Stability: By default, FingerprintJS automatically filters unstable data from customData (timestamps, UUIDs, random values) to ensure fingerprint stability. Use allowUnstableData: true if you need to include this data.

Get Components Only

const fingerprint = new Fingerprint();
const components = await fingerprint.getComponents();

console.log(components);
// {
//   userAgent: "Mozilla/5.0...",
//   language: ["en-US", "en"],
//   timezone: "America/New_York",
//   screen: { width: 1920, height: 1080, ... },
//   canvas: "data:image/png;base64,...",
//   webgl: { vendor: "Google Inc.", ... },
//   ...
// }

🎯 Available Collectors

| Collector | Description | Exclusion Option | | ----------- | -------------------------------- | ------------------------- | | userAgent | Browser User-Agent | ❌ (always included) | | language | Preferred languages | excludeLanguage | | timezone | Timezone | excludeTimezone | | screen | Screen resolution and properties | excludeScreenResolution | | plugins | Installed plugins | excludePlugins | | canvas | Canvas 2D fingerprint | excludeCanvas | | webgl | WebGL information | excludeWebGL | | audio | Audio fingerprint | excludeAudio | | fonts | Available fonts | excludeFonts |

📈 Confidence Level

The confidence level indicates fingerprint reliability:

• 90-100%: Very reliable, many components available
• 70-89%: Reliable, some components missing
• 50-69%: Moderately reliable, several components unavailable
• < 50%: Low reliability, few components available

🕵️ Suspect Analysis

FingerprintJS includes advanced bot and fraud detection:

Suspect Score (0-100)

• 0-30: Legitimate user ✅
• 30-70: Requires vigilance ⚠️
• 70-100: Likely malicious 🚨

Detection Capabilities

• Automation Tools: Selenium, PhantomJS, Puppeteer
• Headless Browsers: Chrome headless, etc.
• Inconsistencies: Timezone/language mismatches
• Bot Signatures: Known crawler patterns
• Environmental Anomalies: Missing APIs, suspicious user agents

Example Usage

const result = await Fingerprint.generate({
  includeSuspectAnalysis: true,
});

if (result.suspectAnalysis.score > 70) {
  // Block or challenge suspicious users
  console.log("Suspicious activity detected");
  console.log("Signals:", result.suspectAnalysis.signals);
} else if (result.suspectAnalysis.score > 30) {
  // Require additional authentication
  console.log("Moderate risk detected");
} else {
  // Allow normal access
  console.log("Legitimate user");
}

🛡️ Security Considerations

This library is designed for:

• Two-factor authentication
• Fraud detection
• Anonymous analytics
• Experience personalization

Important: Respect user privacy and local regulations (GDPR, etc.).

🔄 Fingerprint Stability

FingerprintJS automatically ensures fingerprint stability by filtering unstable data:

✅ Stable Data (kept)

• Static browser properties
• Stable custom data (version, configuration, etc.)
• Hardware characteristics

❌ Unstable Data (automatically filtered)

• timestamp, time, now, date
• random, rand, nonce, salt
• sessionId, requestId, uuid
• UUIDs and temporary identifiers
• Numbers that look like timestamps

Automatic Filtering Example

const fp = new Fingerprint({
  customData: {
    // ✅ Kept (stable)
    version: "1.0",
    theme: "dark",

    // ❌ Automatically filtered (unstable)
    timestamp: Date.now(),
    sessionId: "123e4567-e89b-12d3-a456-426614174000",
    random: Math.random(),
  },
});

// Result: only version and theme will be included

If you absolutely need to include unstable data:

const fp = new Fingerprint({
  allowUnstableData: true, // ⚠️ Disables filtering
  customData: {
    timestamp: Date.now(), // Will make fingerprint unstable
  },
});

🔧 Custom Collectors Usage

import { Fingerprint, CanvasCollector, WebGLCollector } from "fingerprinter-js";

// Use only specific collectors
const canvas = new CanvasCollector();
const canvasData = await canvas.collect();

const webgl = new WebGLCollector();
const webglData = await webgl.collect();

📱 Compatibility

• Browsers: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+
• Node.js: Not supported (browser environment only)
• TypeScript: Full support

🤝 API Reference

Fingerprint Class

constructor(options?: FingerprintOptions)

Creates a new Fingerprint instance.

generate(): Promise<FingerprintResult>

Generates a complete fingerprint.

getComponents(): Promise<Record<string, any>>

Gets components without generating hash.

Static Methods

Fingerprint.generate(options?: FingerprintOptions): Promise<FingerprintResult>

Quickly generates a fingerprint with default options.

Fingerprint.getAvailableCollectors(): string[]

Returns the list of available collectors.

Types

interface FingerprintResult {
  fingerprint: string; // Fingerprint hash
  components: Record<string, any>; // Collected data
  confidence: number; // Confidence level (0-100)
  suspectAnalysis?: SuspectAnalysis; // Optional suspect analysis
}

interface SuspectAnalysis {
  score: number; // Suspect score (0-100)
  riskLevel: "LOW" | "MEDIUM" | "HIGH";
  signals: SuspectSignal[];
  details: Record<string, any>;
}

🚀 Use Cases

Fraud Detection

const result = await Fingerprint.generate({ includeSuspectAnalysis: true });
if (result.suspectAnalysis.score > 80) {
  // Block transaction
}

Bot Protection

const result = await Fingerprint.generate({ includeSuspectAnalysis: true });
const automationSignals = result.suspectAnalysis.signals.filter((s) =>
  ["webdriver", "headless", "selenium"].includes(s.type)
);
if (automationSignals.length > 0) {
  // Challenge with CAPTCHA
}

Analytics Quality

const result = await Fingerprint.generate({ includeSuspectAnalysis: true });
if (result.suspectAnalysis.score < 40) {
  // Include in analytics
  track("page_view", { fingerprint: result.fingerprint });
}

📄 License

MIT © Lorenzo Coslado

🤝 Contributing

Contributions are welcome! Please read the contributing guide before submitting a PR.

📞 Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions