@tracetail/react/README.md

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

# @tracetail/react

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

[![npm version](https://badge.fury.io/js/@tracetail/react.svg)](https://www.npmjs.com/package/@tracetail/react)
[![Downloads](https://img.shields.io/npm/dm/@tracetail/react)](https://www.npmjs.com/package/@tracetail/react)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![React](https://img.shields.io/badge/React-18%2B-blue.svg)](https://reactjs.org/)

## 🚀 Quick Start

```bash
npm install @tracetail/react
```

```tsx
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.

```tsx
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>
  );
}
```

### `useEnhancedTraceTail`

Enhanced fingerprinting with fraud detection capabilities.

```tsx
import { useEnhancedTraceTail } from '@tracetail/react';

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

  if (loading) return <div>Analyzing security...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <div className={`alert ${fingerprint?.threatLevel}`}>
        <h3>Security Analysis</h3>
        <p>Risk Level: {fingerprint?.threatLevel}</p>
        <p>Risk Score: {(fingerprint?.riskScore * 100).toFixed(1)}%</p>
        <p>Bot Probability: {(fingerprint?.botProbability * 100).toFixed(1)}%</p>
        
        {fingerprint?.fraudSignals.length > 0 && (
          <div>
            <h4>Fraud Signals:</h4>
            <ul>
              {fingerprint.fraudSignals.map((signal, i) => (
                <li key={i}>{signal}</li>
              ))}
            </ul>
          </div>
        )}
        
        {fingerprint?.geolocation && (
          <p>Location: {fingerprint.geolocation.city}, {fingerprint.geolocation.country}</p>
        )}
      </div>
    </div>
  );
}
```

### `useVisitorId`

Simplified hook focused on visitor identification with persistence.

```tsx
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>
  );
}
```

### `useFraudDetection`

Specialized hook for fraud detection with configurable thresholds.

```tsx
import { useFraudDetection } from '@tracetail/react';

function FraudCheck() {
  const { 
    isFraudulent, 
    riskLevel, 
    riskScore, 
    botProbability,
    fraudSignals,
    loading, 
    recheck 
  } = useFraudDetection({
    apiKey: 'your-api-key',
    riskThreshold: 0.7,  // Fraud threshold (0-1)
    botThreshold: 0.5    // Bot detection threshold (0-1)
  });

  if (loading) return <div>🔍 Checking for fraud...</div>;

  if (isFraudulent) {
    return (
      <div className="fraud-alert">
        <h3>⚠️ High Risk Detected</h3>
        <p>Additional verification required</p>
        <p>Risk Score: {(riskScore * 100).toFixed(1)}%</p>
        <p>Bot Probability: {(botProbability * 100).toFixed(1)}%</p>
        <button onClick={recheck}>Recheck</button>
      </div>
    );
  }

  return (
    <div className="fraud-clear">
      <h3>✅ Security Check Passed</h3>
      <p>Risk Level: {riskLevel}</p>
      <p>Score: {(riskScore * 100).toFixed(1)}%</p>
    </div>
  );
}
```

## 🌟 Advanced Usage

### Server-Side Rendering (SSR)

```tsx
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

```tsx
import { useEnhancedTraceTail } from '@tracetail/react';

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

  const securityStatus = fingerprint ? {
    isSecure: fingerprint.riskScore < 0.3,
    needsVerification: fingerprint.riskScore > 0.7,
    isBot: fingerprint.botProbability > 0.5,
    level: fingerprint.threatLevel
  } : null;

  return { securityStatus, loading, error };
}

// Usage
function App() {
  const { securityStatus, loading } = useSecurityCheck();
  
  if (loading) return <div>Security check...</div>;
  
  return (
    <div>
      {securityStatus?.needsVerification ? (
        <AdditionalVerification />
      ) : (
        <MainContent />
      )}
    </div>
  );
}
```

### Integration with React Query

```tsx
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:

```tsx
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

```tsx
import { lazy, Suspense } from 'react';

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

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

### Conditional Loading

```tsx
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

```tsx
// 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

```tsx
// 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:** support@tracetail.io

## 📝 License

MIT License - see [LICENSE](LICENSE) file for details.

---

**[Get your API key](https://tracetail.io/auth) • [View Documentation](https://tracetail.io/docs) • [Try Live Demo](https://tracetail.io/live-demo)**