JavaScript SDK

Installation

npm install @fingerprintiq/js

yarn add @fingerprintiq/js

pnpm add @fingerprintiq/js

<script src="https://cdn.fingerprintiq.com/v1/fiq.min.js"></script>
<script>
  const fiq = new FingerprintIQ({ apiKey: 'fiq_live_...' });
  fiq.identify().then(result => console.log(result.visitorId));
</script>

Basic Usage

javascript
import FingerprintIQ from '@fingerprintiq/js';

const fiq = new FingerprintIQ({
  apiKey: 'fiq_live_your_key',
  endpoint: 'https://api.fingerprintiq.com', // default
  timeout: 10000, // 10 seconds (default)
  detectWallets: true, // detect Web3 wallets (default: true)
});

// Identify the current device
const result = await fiq.identify();

Instantiate FingerprintIQ once at module load time, not inside an event handler or on each page load. The instance is lightweight and reusable across multiple identify() calls.

Configuration Options

Response Type

typescript
interface IdentifyResponse {
  visitorId: string;      // Stable device identifier
  visitCount: number;     // Total visits by this device
  firstSeenAt: number;    // Unix timestamp (ms) of first visit
  confidence: number;     // 0.0 - 1.0 signal confidence score
  botProbability: number; // 0.0 - 1.0 bot likelihood score
  signals: {
    client: Record<string, unknown>; // All 29 client signals
    server: {
      asn: { asn: number; org: string; category: string };
      geo: { country: string; city: string; rttCoherence: number };
      tls: { cipher: string; version: string; protocol: string };
      consistency: string[];
    };
  };
  riskFactors: string[];  // Active risk indicators
  timestamp: number;      // Unix timestamp (ms) of this visit
}

Error Handling

javascript
try {
  const result = await fiq.identify();
  // handle result
} catch (error) {
  if (error.message.includes('429')) {
    // Rate limited — retry after a delay, or show a fallback
    console.warn('FingerprintIQ rate limit hit');
  } else if (error.message.includes('401')) {
    // Invalid or missing API key — check your configuration
    console.error('Invalid FingerprintIQ API key');
  } else {
    // Network timeout or connectivity issue
    console.error('FingerprintIQ request failed:', error.message);
  }
}

If identify() fails, your application should degrade gracefully — don't block the user experience. Log the error and continue without the fingerprint when possible.

Use Cases

javascript
const result = await fiq.identify();

if (result.visitCount > 1) {
  // This device has been seen before — check trial status
  const hasUsedTrial = await checkTrialStatus(result.visitorId);
  if (hasUsedTrial) {
    showPaywall();
  }
}

javascript
const result = await fiq.identify();

if (result.botProbability > 0.7) {
  // Very likely a bot — block or hard challenge
  blockRequest();
} else if (result.botProbability > 0.3) {
  // Suspicious — show CAPTCHA
  showCaptcha();
} else if (result.botProbability > 0.1) {
  // Slightly elevated — increase monitoring
  logSuspiciousActivity(result);
}

javascript
const result = await fiq.identify();
const wallets = result.signals.client.wallets;

if (wallets && wallets.count > 0) {
  console.log('Detected wallets:', wallets.detected);
  // ["MetaMask", "Phantom"]

  // Same device with multiple wallet addresses = potential Sybil
  if (result.visitCount > 5 && wallets.multipleWallets) {
    flagForReview(result.visitorId);
  }
}

javascript
const fiq = new FingerprintIQ({
  apiKey: 'fiq_live_...',
  endpoint: 'https://fp.yoursite.com', // proxy to api.fingerprintiq.com
});