# @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://img.shields.io/npm/v/@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>
  );
}
```


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


## 🌟 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 { 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

```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)**