Generic JavaScript agent wrapper for SPAs

Deprecated in v4In Fingerprint v4, the caching functionality from @fingerprintjs/fingerprintjs-pro-spa has been incorporated directly into the JavaScript agent. You no longer need this wrapper library.If you are using Fingerprint v3, see the v3 documentation.

Migration guide

Follow these steps to migrate from @fingerprintjs/fingerprintjs-pro-spa to the v4 JavaScript agent.

1. Update dependencies

Remove the SPA library and install the v4 agent:

npm uninstall @fingerprintjs/fingerprintjs-pro-spa
npm install @fingerprint/agent

2. Update imports and initialization

The v4 agent uses Fingerprint.start() instead of creating a FpjsClient instance and calling init().

SPA library to v4 agent

import { FpjsClient, FingerprintJSPro } from "@fingerprintjs/fingerprintjs-pro-spa"; 
import * as Fingerprint from "@fingerprint/agent"; 

const fpjsClient = new FpjsClient({
  loadOptions: {
    apiKey: "PUBLIC_API_KEY", 
    endpoint: ["https://metrics.yourwebsite.com", FingerprintJSPro.defaultEndpoint], 
    region: "eu", 
  }, 
  cacheLocation: "sessionStorage", 
  cacheTimeInSeconds: 3600, 
}); 
await fpjsClient.init(); 
const agent = Fingerprint.start({
  apiKey: "PUBLIC_API_KEY", 
  endpoints: "https://metrics.yourwebsite.com", 
  region: "eu", 
  cache: {
    storage: "sessionStorage", 
    duration: 3600, 
  }, 
}); 

3. Update identification calls

Replace getVisitorData() with get().

getVisitorData to get

const visitorData = await fpjsClient.getVisitorData(); 
console.log(visitorData.visitorId); 
const result = await agent.get(); 
console.log(result.visitor_id); 

The v4 agent no longer supports extendedResult. Extended data like IP address and geolocation should be retrieved server-side using the Server API or Sealed Client Results.

4. Update cache configuration

The cache options have been renamed:

SPA library	v4 agent
`cacheLocation: 'sessionStorage'`	`cache: { storage: 'sessionStorage', ... }`
`cacheLocation: 'localStorage'`	`cache: { storage: 'localStorage', ... }`
`cacheLocation: 'memory'`	`cache: { storage: 'agent', ... }`
`cacheLocation: 'nocache'`	Omit the `cache` option entirely
`cacheTimeInSeconds: 3600`	`cache: { duration: 3600, ... }` or `cache: { duration: 'optimize-cost', ... }`

The v4 agent also provides two convenient duration presets:

'optimize-cost' — caches for 1 hour
'aggressive' — caches for 12 hours (not recommended for fraud prevention)

5. Check for cached results

The cacheHit property is now cache_hit in the response:

cacheHit to cache_hit

const { cacheHit, ...visitorData } = await fpjsClient.getVisitorData(); 
if (cacheHit) {
  console.log("Result was from cache"); 
} 
const result = await agent.get(); 
if (result.cache_hit) {
  console.log("Result was from cache"); 
} 

For more details about the v4 JavaScript agent, see the JavaScript agent reference.

Understanding Fingerprint

Identify browsers

Identify mobile devices

AI

Rules Engine and Flow (Beta)

Protect your implementation

Integrate with your server

Integrate Smart Signals

Device reputation network

Tips and advanced guides

Platform updates

Resources

Legal

Generic JavaScript agent wrapper for SPAs

Migration guide

1. Update dependencies

2. Update imports and initialization

3. Update identification calls

4. Update cache configuration

5. Check for cached results

​Migration guide

​1. Update dependencies

​2. Update imports and initialization

​3. Update identification calls

​4. Update cache configuration

​5. Check for cached results

Migration guide

1. Update dependencies

2. Update imports and initialization

3. Update identification calls

4. Update cache configuration

5. Check for cached results