JavaScript SDK Reference

Class: FingerprintIQ

Constructor

typescript
new FingerprintIQ(config: FingerprintIQConfig)

Methods

identify(options?: IdentifyOptions): Promise<IdentifyResponse>

Collects all configured signals in parallel and sends them to the FingerprintIQ API. Returns the compact identification result including the stable visitorId, requestId, verdicts, and scores. Full signal data is available server-side via the Events API using result.requestId.

typescript
const fiq = new FingerprintIQ({ apiKey: 'fiq_live_...' });

// Basic usage
const result = await fiq.identify();
console.log(result.visitorId);      // "iq_01hns3k6tez83695a6t714s6n1"
console.log(result.requestId);      // "req_01hns3k6tez83695a6t7"
console.log(result.visitCount);     // 3
console.log(result.botProbability); // 0.05
console.log(result.suspectScore);   // 0

// With metadata and per-call options
const result = await fiq.identify({
  tag: { page: 'checkout', experiment: 'v2' },
  linkedId: 'user_123',
  timeout: 5000,
});

Options:

Throws:

• Error if the API returns a non-200 status (message includes the HTTP status code)
• Error if the request exceeds the configured timeout
• Error if apiKey is not provided in the constructor config

The FingerprintIQ instance is lightweight and safe to reuse. Instantiate it once at module scope and call identify() whenever you need a fingerprint — don't create a new instance on each call.

Types

FingerprintIQConfig

typescript
interface FingerprintIQConfig {
  apiKey: string;
  endpoint?: string;         // default: 'https://api.fingerprintiq.com'
  timeout?: number;          // default: 10000 (ms)
  detectWallets?: boolean;   // default: true
  cache?: {
    storage: 'sessionStorage' | 'localStorage' | 'memory';
    ttl: number;             // seconds
  };
}

IdentifyOptions

typescript
interface IdentifyOptions {
  tag?: Record<string, string>;  // Arbitrary metadata for this event
  linkedId?: string;             // Entity ID to link this event to
  timeout?: number;              // Per-call timeout override (ms)
}

IdentifyResponse

typescript
interface IdentifyResponse {
  requestId: string;        // Unique event identifier (format: req_<ulid>)
  visitorId: string;        // Stable device identifier (format: iq_<ulid>)
  confidence: number;       // 0.0 - 1.0 signal confidence
  botProbability: number;   // 0.0 - 1.0 bot likelihood
  suspectScore: number;     // 0 - 100 composite risk score
  visitCount: number;       // Total visits from this device
  firstSeenAt: number;      // Unix timestamp (ms) of first identification
  lastSeenAt: number;       // Unix timestamp (ms) of previous identification
  verdicts: {
    bot: { result: boolean; probability: number };
    vpn: { result: boolean; confidence: number };
    tor: { result: boolean };
    proxy: { result: boolean };
    incognito: { result: boolean };
    tampering: { result: boolean; anomalyScore: number };
    headless: { result: boolean };
    virtualMachine: { result: boolean };
    devtools: { result: boolean };
    privacyBrowser: { result: boolean; name: string | null };
    highActivity: { result: boolean };
    ipBlocklist: { result: boolean };
  };
  ip: string;               // Client IP address
  ipLocation: {
    country: string;
    city: string;
    region: string;
    latitude: number;
    longitude: number;
  };
  riskFactors: string[];    // Active risk indicators
  timestamp: number;        // Unix timestamp (ms) of this visit
}

Bundle Size

The SDK is designed to be lightweight. Signal collection code is bundled inline — no dynamic imports or external dependencies.

Browser Support

Older browsers that lack specific APIs (e.g., OfflineAudioContext, WebGL) will return null for those signals rather than throwing. The core fingerprint remains functional with reduced signal coverage.