@tracetail/react

React hooks for TraceTail enterprise browser fingerprinting with over 99.5% accuracy. Built for React 18 with full TypeScript support.

🚀 Quick Start

npm install @tracetail/react

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

function App() {
  const { fingerprint, loading, error } = useTraceTail({
    apiKey: 'your-api-key',
    immediate: true
  });

  if (loading) return <div>Generating fingerprint...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  return <div>Visitor ID: {fingerprint?.visitorId}</div>;
}

✨ Features

• 🎯 Over 99.5% accuracy - Industry-leading device identification
• ⚡ React optimized - Built specifically for React with hooks
• 🔒 Enterprise security - Bank-grade fraud detection hooks
• 📱 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
• 🎣 React 18 ready - Supports concurrent features and Suspense

🎣 Hooks Reference

useTraceTail

Basic fingerprinting hook for visitor identification.

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

function MyComponent() {
  const { fingerprint, loading, error, generate, regenerate } = useTraceTail({
    apiKey: 'tt_prod_...',
    immediate: true,     // Generate on mount
    caching: true,       // Cache results
    debug: false         // Enable debug logging
  });

  return (
    <div>
      {loading && <p>Generating fingerprint...</p>}
      {error && <p>Error: {error.message}</p>}
      {fingerprint && (
        <div>
          <p>Visitor ID: {fingerprint.visitorId}</p>
          <p>Confidence: {(fingerprint.confidence * 100).toFixed(1)}%</p>
          <p>Processing Time: {fingerprint.processingTime}ms</p>
        </div>
      )}
      <button onClick={regenerate} disabled={loading}>
        Regenerate Fingerprint
      </button>
    </div>
  );
}

useVisitorId

Simplified hook focused on visitor identification with persistence.

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

function UserTrackingComponent() {
  const { 
    visitorId, 
    isReturningVisitor, 
    loading, 
    error, 
    refresh 
  } = useVisitorId({
    apiKey: 'your-api-key',
    storageKey: 'my_app_visitor_id' // Custom localStorage key
  });

  return (
    <div>
      {loading && <p>Identifying visitor...</p>}
      {error && <p>Error: {error.message}</p>}
      {visitorId && (
        <div>
          <p>Visitor ID: {visitorId}</p>
          <p>Status: {isReturningVisitor ? '🔄 Returning' : '✨ New'} visitor</p>
          <button onClick={refresh}>Refresh ID</button>
        </div>
      )}
    </div>
  );
}

🌟 Advanced Usage

Server-Side Rendering (SSR)

import { useEffect, useState } from 'react';
import { useTraceTail } from '@tracetail/react';

function SSRSafeComponent() {
  const [isClient, setIsClient] = useState(false);
  
  // Only run fingerprinting on client-side
  const { fingerprint, loading } = useTraceTail({
    apiKey: 'your-api-key',
    immediate: isClient
  });

  useEffect(() => {
    setIsClient(true);
  }, []);

  if (!isClient) {
    return <div>Loading...</div>;
  }

  return (
    <div>
      {loading ? 'Generating...' : `ID: ${fingerprint?.visitorId}`}
    </div>
  );
}

Custom Hook Pattern

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

function useVisitorTracking() {
  const { fingerprint, loading, error } = useTraceTail({
    apiKey: process.env.REACT_APP_TRACETAIL_KEY!,
    immediate: true
  });

  const trackingData = fingerprint ? {
    visitorId: fingerprint.visitorId,
    confidence: fingerprint.confidence,
    isHighConfidence: fingerprint.confidence > 0.95,
    processingTime: fingerprint.processingTime
  } : null;

  return { trackingData, loading, error };
}

// Usage
function App() {
  const { trackingData, loading } = useVisitorTracking();
  
  if (loading) return <div>Identifying visitor...</div>;
  
  return (
    <div>
      <p>Visitor: {trackingData?.visitorId}</p>
      <p>Confidence: {(trackingData?.confidence * 100).toFixed(1)}%</p>
    </div>
  );
}

Integration with React Query

import { useQuery } from '@tanstack/react-query';
import { useTraceTail } from '@tracetail/react';

function useUserProfile() {
  const { fingerprint } = useTraceTail({
    apiKey: 'your-api-key',
    immediate: true
  });

  return useQuery({
    queryKey: ['userProfile', fingerprint?.visitorId],
    queryFn: () => fetchUserProfile(fingerprint?.visitorId),
    enabled: !!fingerprint?.visitorId
  });
}

🔧 TypeScript Support

Full TypeScript definitions included:

import type { 
  FingerprintResult, 
  EnhancedFingerprintResult, 
  UseTraceTailReturn 
} from '@tracetail/react';

const MyComponent: React.FC = () => {
  const result: UseTraceTailReturn = useTraceTail({
    apiKey: 'your-key',
    immediate: true
  });

  // Full type safety
  const visitorId: string | null = result.fingerprint?.visitorId || null;
  const confidence: number = result.fingerprint?.confidence || 0;
  
  return <div>{visitorId}</div>;
};

⚡ Performance Optimization

Lazy Loading

import { lazy, Suspense } from 'react';

const FingerprintComponent = lazy(() => import('./FingerprintComponent'));

function App() {
  return (
    <Suspense fallback={<div>Loading security...</div>}>
      <FingerprintComponent />
    </Suspense>
  );
}

Conditional Loading

function ConditionalFingerprinting() {
  const [needsFingerprint, setNeedsFingerprint] = useState(false);
  
  const { fingerprint, loading } = useTraceTail({
    apiKey: 'your-api-key',
    immediate: needsFingerprint // Only when needed
  });

  return (
    <div>
      <button onClick={() => setNeedsFingerprint(true)}>
        Enable Security Check
      </button>
      {needsFingerprint && (
        <div>
          {loading ? 'Checking...' : `ID: ${fingerprint?.visitorId}`}
        </div>
      )}
    </div>
  );
}

🌐 Browser Support

• Chrome 80+
• Firefox 75+
• Safari 13+
• Edge 80+
• React Native WebView
• Electron

🔄 Migration Guide

From @tracetail/js

// Before (vanilla JS)
import { TraceTail } from '@tracetail/js';
const tracetail = new TraceTail({ apiKey: 'key' });
const fingerprint = await tracetail.generateFingerprint();

// After (React hooks)
import { useTraceTail } from '@tracetail/react';
const { fingerprint, loading } = useTraceTail({ 
  apiKey: 'key', 
  immediate: true 
});

From other libraries

// Replace custom fingerprinting hooks
const { fingerprint } = useTraceTail({
  apiKey: 'your-key',
  immediate: true
});

// Same visitor ID across sessions and devices
const visitorId = fingerprint?.visitorId;

📞 Support

• Documentation: https://tracetail.io/docs
• API Reference: https://tracetail.io/api-docs
• Support: https://tracetail.io/support
• Discord: https://discord.gg/tracetail
• Email: [email protected]

📝 License

MIT License - see LICENSE file for details.

Get your API key • View Documentation • Try Live Demo