Skip to main content
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 libraryv4 agent
cacheLocation: 'sessionStorage'cache: { storage: 'sessionStorage', ... }
cacheLocation: 'localStorage'cache: { storage: 'localStorage', ... }
cacheLocation: 'memory'cache: { storage: 'agent', ... }
cacheLocation: 'nocache'Omit the cache option entirely
cacheTimeInSeconds: 3600cache: { 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.