@tracetail/js

Enterprise browser fingerprinting with over 99.5% accuracy. Zero dependencies, TypeScript support, and rock-solid stability.

🚀 Quick Start

npm install @tracetail/js

import TraceTail from '@tracetail/js';

// Initialize with API key
const tracetail = new TraceTail({
  apiKey: 'your-api-key',
  debug: false
});

// Generate fingerprint
const result = await tracetail.generateFingerprint();
console.log('Visitor ID:', result.visitorId);
console.log('Confidence:', (result.confidence * 100).toFixed(1) + '%');

✨ Features

• 🎯 Over 99.5% accuracy - Industry-leading device identification
• ⚡ Zero dependencies - Lightweight and fast (27KB bundle)
• 🔒 Enterprise security - Bank-grade fraud detection
• 📱 Cross-platform - Works on all browsers and devices
• 🔧 TypeScript - Full type safety and IntelliSense
• 🌐 Incognito consistent - Same ID across normal and private browsing
• 🚀 Performance optimized - <25ms fingerprint generation

📖 API Reference

new TraceTail(options)

Create a new TraceTail instance.

const tracetail = new TraceTail({
  apiKey: 'tt_live_abc123xyz789',  // Required: Your API key
  endpoint: 'https://tracetail.io/api', // Optional: Custom endpoint
  debug: true                       // Optional: Enable debug logging
});

Parameters:

• apiKey (string): Your TraceTail API key (required)
• endpoint (string): Custom API endpoint (optional)
• debug (boolean): Enable debug logging (optional)

tracetail.generateFingerprint(options?)

Generate a browser fingerprint with visitor identification.

// Basic usage
const result = await tracetail.generateFingerprint();

// With detailed components
const detailedResult = await tracetail.generateFingerprint({
  verbose: true  // Include raw component data
});

Parameters:

• options.verbose (boolean): Include detailed component data

Returns: Promise<FingerprintResult>

interface FingerprintResult {
  visitorId: string;           // Unique visitor identifier
  confidence: number;          // Accuracy confidence (0-1)
  processingTime: number;      // Generation time in milliseconds
  timestamp: string;           // ISO timestamp
  version: string;             // SDK version (2.3.3)
  signalCount: number;         // Number of signals collected
  components?: ComponentData;  // Raw signal data (verbose mode)
}

TraceTail.version

Get the SDK version (static property).

console.log('SDK Version:', TraceTail.version); // "2.3.3"

🎯 Usage Examples

Basic Visitor Identification

import TraceTail from '@tracetail/js';

// Initialize once
const tracetail = new TraceTail({
  apiKey: process.env.TRACETAIL_API_KEY
});

// Use throughout your app
async function identifyVisitor() {
  try {
    const result = await tracetail.generateFingerprint();
    
    console.log({
      visitorId: result.visitorId,      // "fp_abc123def456"
      confidence: result.confidence,    // 0.995 (99.5% accurate)
      processingTime: result.processingTime, // 18ms
      signalCount: result.signalCount   // 45 signals collected
    });
    
    return result.visitorId;
  } catch (error) {
    console.error('Fingerprinting failed:', error);
    return null;
  }
}

Advanced Usage with Components

// Get detailed fingerprint data
const detailed = await tracetail.generateFingerprint({ verbose: true });

console.log({
  visitorId: detailed.visitorId,
  confidence: detailed.confidence,
  components: {
    canvas: detailed.components.canvas,      // Canvas fingerprint
    webgl: detailed.components.webgl,        // WebGL parameters
    audio: detailed.components.audio,        // Audio context
    fonts: detailed.components.fonts,        // Font detection
    hardware: detailed.components.hardware   // Hardware info
  }
});

Error Handling

async function safeFingerprinting() {
  try {
    const result = await tracetail.generateFingerprint();
    
    if (result.confidence > 0.9) {
      // High confidence - reliable identification
      return result.visitorId;
    } else {
      // Lower confidence - may want to retry or use fallback
      console.warn('Lower confidence fingerprint');
      return result.visitorId;
    }
  } catch (error) {
    console.error('Fingerprinting error:', error);
    
    // Implement fallback identification
    return generateFallbackId();
  }
}

Caching Results

const CACHE_KEY = 'tracetail_visitor_id';
const CACHE_TTL = 3600000; // 1 hour

async function getCachedFingerprint() {
  // Check cache first
  const cached = localStorage.getItem(CACHE_KEY);
  if (cached) {
    const data = JSON.parse(cached);
    if (Date.now() - data.timestamp < CACHE_TTL) {
      return data.visitorId;
    }
  }
  
  // Generate new fingerprint
  const result = await tracetail.generateFingerprint();
  
  // Cache result
  localStorage.setItem(CACHE_KEY, JSON.stringify({
    visitorId: result.visitorId,
    timestamp: Date.now()
  }));
  
  return result.visitorId;
}

🌐 CDN Usage

For quick integration without NPM:

<script src="https://tracetail.io/sdk.js" 
        data-api-key="your-api-key"></script>
<script>
  TraceTail.generateFingerprint().then(result => {
    console.log('Visitor ID:', result.visitorId);
    console.log('Confidence:', (result.confidence * 100).toFixed(1) + '%');
  });
</script>

🔧 TypeScript Support

Full TypeScript support with comprehensive type definitions:

import TraceTail, { FingerprintResult, ComponentData } from '@tracetail/js';

// Initialize with types
const tracetail = new TraceTail({
  apiKey: process.env.TRACETAIL_API_KEY!,
  debug: process.env.NODE_ENV !== 'production'
});

// Typed results
const result: FingerprintResult = await tracetail.generateFingerprint();

// Type-safe component access
if (result.components) {
  const canvas: ComponentData = result.components.canvas;
  const webgl: ComponentData = result.components.webgl;
}

🎭 Framework Integrations

React

npm install @tracetail/react

import { useTraceTail } from '@tracetail/react';

function App() {
  const { fingerprint, loading } = useTraceTail({
    apiKey: 'your-api-key'
  });
  
  return <div>Visitor: {fingerprint?.visitorId}</div>;
}

Vue 3

npm install @tracetail/vue

<script setup>
import { useFingerprint } from '@tracetail/vue';

const { visitorId, loading } = useFingerprint();
</script>

<template>
  <div>Visitor: {{ visitorId }}</div>
</template>

Angular

npm install @tracetail/angular

import { TraceTailService } from '@tracetail/angular';

@Component({
  template: `<div>Visitor: {{ fingerprint$ | async | json }}</div>`
})
export class MyComponent {
  fingerprint$ = this.traceTail.fingerprint$;
  
  constructor(private traceTail: TraceTailService) {}
}

🛠️ Development

# Clone repository
git clone https://github.com/tracetail/tracetail.git

# Install dependencies
npm install

# Run tests
npm test

# Build package
npm run build

📊 Performance

• Bundle Size: 27KB minified + gzipped
• Generation Time: <25ms average
• Accuracy: >99.5% unique identification
• Browser Support: All modern browsers + IE11
• Caching: Automatic 1-hour local caching

🔒 Privacy & Security

• GDPR Compliant: No PII collected by default
• Secure: Client-side processing with optional server enhancement
• Transparent: Open source and auditable
• Configurable: Respect user privacy preferences

📈 Use Cases

• Fraud Prevention: Detect suspicious users and prevent account takeovers
• Analytics: Track unique visitors without cookies
• Personalization: Provide consistent experience across sessions
• Security: Implement device-based authentication
• A/B Testing: Ensure consistent test groups

🆘 Support

• Documentation: docs.tracetail.io
• API Reference: tracetail.io/api/docs
• GitHub Issues: github.com/tracetail/tracetail/issues
• Email: [email protected]
• Discord: discord.gg/tracetail

📄 License

MIT - see LICENSE for details.