SDK Configuration

Configure the FingerprintIQ SDK for your use case.

All Options

typescript
const fiq = new FingerprintIQ({
  apiKey: 'fiq_live_your_key',               // Required
  endpoint: 'https://api.fingerprintiq.com', // Optional
  timeout: 10000,                             // Optional, ms
  detectWallets: true,                        // Optional
  cache: {                                    // Optional
    storage: 'sessionStorage',
    ttl: 3600,
  },
});

Option Reference

apiKey string required

Your API key from the FingerprintIQ dashboard. The only required option.

  • fiq_live_* — Production key. Counts toward your monthly quota.
  • fiq_test_* — Development key. Full functionality, excluded from quota.
endpoint string

The API endpoint to send identification requests to. Defaults to https://api.fingerprintiq.com.

Override this to route traffic through your own domain (useful for avoiding ad blockers or maintaining a first-party data relationship).

timeout number

Maximum time in milliseconds to wait for the identification request to complete. Defaults to 10000 (10 seconds).

This covers both signal collection time (~50–150 ms) and the network round-trip. Only reduce this below 5000 ms if you're certain your users have fast, reliable connections.

detectWallets boolean

Whether to enumerate Web3 wallet extensions. Defaults to true.

Wallet detection adds approximately 50 ms to the collection phase. Disable it on non-Web3 sites or performance-critical pages where wallet data is not needed.

cache object

Caching configuration to avoid redundant identifications within a session or across page loads.

  • storage — Where to persist the cached result: "sessionStorage" (default, cleared when tab closes), "localStorage" (persists across sessions), or "memory" (cleared on page reload).
  • ttl — Time-to-live in seconds. After expiry, the next identify() call makes a fresh API request. Defaults to 3600 (1 hour) when cache is configured.

When a cached result is returned, identify() resolves immediately without collecting signals or making a network request. The cached requestId and visitorId remain valid for server-side lookups.

Common Configurations

Production (default)

typescript
const fiq = new FingerprintIQ({
  apiKey: process.env.FIQ_API_KEY,
});

Custom Proxy Endpoint

Route FingerprintIQ traffic through your own domain to avoid ad blockers:

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

A Cloudflare Worker is an ideal proxy — it adds zero latency if deployed on the same network as the FingerprintIQ edge API.

Disable Wallet Detection

For non-Web3 sites where wallet data is never used:

typescript
const fiq = new FingerprintIQ({
  apiKey: 'fiq_live_...',
  detectWallets: false, // saves ~50ms
});

Extended Timeout for Slow Networks

For mobile-first applications or regions with high latency:

typescript
const fiq = new FingerprintIQ({
  apiKey: 'fiq_live_...',
  timeout: 20000, // 20 seconds
});

The timeout applies to the entire identify() call including signal collection. Most of the time budget is consumed by the audio signal (~40–80 ms) and the network round-trip.

Session Caching

Cache results for a session to avoid redundant identifications on repeat page views:

typescript
const fiq = new FingerprintIQ({
  apiKey: 'fiq_live_...',
  cache: {
    storage: 'sessionStorage',
    ttl: 3600, // 1 hour
  },
});

For single-page apps where the visitor persists across route changes, use memory storage to avoid any serialization overhead:

typescript
const fiq = new FingerprintIQ({
  apiKey: 'fiq_live_...',
  cache: {
    storage: 'memory',
    ttl: 1800, // 30 minutes
  },
});
Previous JavaScript SDK Reference
Next Signal Types Reference
Ask a question... ⌘I