@bambulabs/finedine-fingerprint-react

React hooks and components for Finedine visitor fingerprinting.

Installation

npm install @bambulabs/finedine-fingerprint-react

Quick Start

Option 1: Simple Hook

import { useVisitorId } from '@bambulabs/finedine-fingerprint-react';

function App() {
  const { visitorId, isLoading, error } = useVisitorId();

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;

  return <div>Visitor ID: {visitorId}</div>;
}

Option 2: Full Visitor Data

import { useVisitorTracking } from '@bambulabs/finedine-fingerprint-react';

function App() {
  const { visitor, isLoading } = useVisitorTracking();

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      <p>ID: {visitor?.id}</p>
      <p>Visits: {visitor?.visitCount}</p>
      <p>Browser: {visitor?.device?.browser?.name}</p>
      <p>Device: {visitor?.device?.device?.type}</p>
    </div>
  );
}

Option 3: Context Provider (Recommended for Apps)

// App.jsx
import { FingerprintProvider } from '@bambulabs/finedine-fingerprint-react';

function App() {
  return (
    <FingerprintProvider>
      <YourApp />
    </FingerprintProvider>
  );
}

// Any component
import { useFingerprint } from '@bambulabs/finedine-fingerprint-react';

function Header() {
  const { visitor, visitorId } = useFingerprint();
  return <span>Welcome! Visit #{visitor?.visitCount}</span>;
}

API Reference

Hooks

useVisitorId(options?)

Simple hook returning just the visitor ID.

const { visitorId, isLoading, error, identify, clear } = useVisitorId({
  apiUrl: 'https://track.finedinemenu.com/fingerprint', // optional
  storageKey: 'fp_visitor_id', // optional
  autoIdentify: true, // optional, default: true
});

useVisitorTracking(options?)

Full hook with complete visitor data.

const { visitor, isLoading, error, identify, clear } = useVisitorTracking({
  apiUrl: 'https://track.finedinemenu.com/fingerprint',
  storageKey: 'fp_visitor_id',
  autoIdentify: true,
});

useFingerprint()

Context hook (use within FingerprintProvider).

const { visitor, visitorId, isLoading, error, identify, clear } = useFingerprint();

Components

<FingerprintProvider>

Context provider for app-wide visitor tracking.

<FingerprintProvider
  apiUrl="https://track.finedinemenu.com/fingerprint"
  storageKey="fp_visitor_id"
  autoIdentify={true}
>
  {children}
</FingerprintProvider>

Standalone Client

For non-React usage:

import { createFingerprintClient } from '@bambulabs/finedine-fingerprint-react';

const client = createFingerprintClient({
  apiUrl: 'https://track.finedinemenu.com/fingerprint',
});

// Identify visitor
const visitor = await client.identify();
console.log(visitor.id, visitor.visitCount);

// Get stored ID
const storedId = client.getStoredId();

// Clear stored data
client.clear();

Types

interface Visitor {
  id: string;
  fingerprint: string;
  isNew: boolean;
  firstSeen: Date;
  visitCount: number;
  device: {
    browser: { name: string; version: string };
    os: { name: string; version: string };
    device: { type: string; vendor: string; model: string };
  };
}

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiUrl | string | https://track.finedinemenu.com/fingerprint | API endpoint | | storageKey | string | fp_visitor_id | localStorage/cookie key | | autoIdentify | boolean | true | Auto-identify on mount |

How It Works

1. Check localStorage - Fastest, checked first
2. Check cookie - Fallback (server-set)
3. Generate fingerprint - Ultimate fallback using FingerprintJS

This ensures visitors are always identified, even after clearing storage.

License

MIT