Fingerprint Pro SPA

Fingerprint is a device intelligence platform offering industry-leading accuracy

This library is a framework-agnostic wrapper around the Fingerprint Pro JavaScript Agent, adding multiple built-in caching mechanisms with recommended default settings.

- If you just need the Fingerprint Pro JS agent without caching, you can use it directly.
- If you're looking for a framework-specific integration, we have dedicated SDKs for React (including Next, Preact), Vue, Svelte and Angular.
- If you have a single-page web application that needs caching, but also more low-level control over the agent than framework-specific SDKs provide, this library is for you.

> [!NOTE]
> This library assumes you have a Fingerprint Pro subscription or trial, it is not compatible with the source-available FingerprintJS. See our documentation to learn more about the differences between Fingerprint Pro and FingerprintJS.

Table of Contents

- Requirements
- Installation
- Getting Started
- Caching
- Support and Feedback
- Documentation
- License

Requirements

- For TypeScript users: Typescript 4.5 or higher

Installation

Using npm:

``sh
npm install @fingerprintjs/fingerprintjs-pro-spa
`

Using yarn:

`sh
yarn add @fingerprintjs/fingerprintjs-pro-spa
`

Using pnpm:

`sh
pnpm add @fingerprintjs/fingerprintjs-pro-spa
`

Getting Started

$3

In order to identify visitors you'll need a Fingerprint Pro account (you can sign up for free).

- Go to Fingerprint Dashboard > App settings > API Keys.
- Find your Public API key.

$3

Create a FpjsClient instance before rendering or initializing your application. You should only have one instance of the client. You need to specify your public API key and other configuration options based on your chosen region and active integration.

`js
import { FpjsClient, FingerprintJSPro } from '@fingerprintjs/fingerprintjs-pro-spa'

const fpjsClient = new FpjsClient({
// You can also pass these options later in .init() method
loadOptions: {
apiKey: '',
endpoint: [
//'https://metrics.yourwebsite.com',
FingerprintJSPro.defaultEndpoint,
],
scriptUrlPattern: [
// 'https://metrics.yourwebsite.com/web/v//loader_v.js',
FingerprintJSPro.defaultScriptUrlPattern,
],
// region: "eu"
},
})
`

> [!NOTE]
> You must provide loadOptions containing your public API key either in the constructor or in the init method. If you don't, the SDK will throw an error. You can learn more about different load options here in the JS Agent documentation.

$3

Before you start making identification requests to the Fingerprint Pro API, you need to initialize the JS Agent. This downloads the latest client-side logic from Fingerprint CDN. Call init() before the getVisitorData() method to avoid errors.

`js
// with async/await
await fpjsClient.init()

const visitorData = await fpjsClient.getVisitorData()

// with promises
const visitorData = fpjsClient.init().then(() => {
return fpjsClient.getVisitorData()
})
`

You can also pass the loadOptions into the init method here. They will be merged with the options passed to the constructor.

`js
await fpjsClient.init({
apiKey: '',
// endpoint: ["", FingerprintJSPro.defaultEndpoint],
// scriptUrlPattern: ["", FingerprintJSPro.defaultScriptUrlPattern],
// region: "eu"
})
`

$3

The getVisitorData method returns visitor identification data based on the request options.
Set ignoreCache to true to call the API even if the data is present in the cache.

`js
// with async/await
const visitorData = await fpjsClient.getVisitorData({ extendedResult: true }, false)

// with promises
const visitorData = fpjsClient.getVisitorData({ extendedResult: true }).then((visitorData) => {
// use visitor data in your fraud prevention logic
checkIfFingerprintIsFraudulent(visitorData.visitorId) // this method is just an example, this SDK doesn't actually supply it
})
`

See the JS Agent API reference for more details.

#### Linking and tagging information

The visitorId provided by Fingerprint Identification is especially useful when combined with information you already know about your users, for example, account IDs, order IDs, etc. To learn more about various applications of the linkedId and tag, see Linking and tagging information.

`js
const visitorData = await fpjsClient.getVisitorData({
linkedId: 'user_1234',
tag: {
userAction: 'login',
analyticsId: 'UA-5555-1111-1',
},
})
`

Caching

Fingerprint Pro usage is billed per API call. To avoid unnecessary API calls, it is a good practice to cache identification results. The SDK provides three ways to cache visitor data out of the box:

- Session storage (default) - sessionStorage
- Local storage - localStorage
- Memory - memory
- No cache - nocache

You can specify the cacheLocation option when creating the FpjsClient:

`js
const fpjsClient = new FpjsClient({
loadOptions: {
apiKey: 'your-fpjs-public-api-key',
},
cacheLocation: 'localstorage',
// You can also use the provided TypeScript enum
// cacheLocation: CacheLocation.LocalStorage
})
`

Cache keys are based on the combination of _GetOptions_. For example, API responses for calls with extendedResult: true and extendedResult: false are stored independently.

> [!NOTE]
> If you use data from extendedResult, pay additional attention to your caching strategy. Some fields, for example, ip or lastSeenAt, might change over time for the same visitor.

You can ignore the cached result for a specific API call and using { ignoreCache: true }:

`js
const visitorData = await fpjsClient.getVisitorData({ ignoreCache: true })
`

Check if your response was retrieved from cache using the returned cacheHit flag:

`js
const { cacheHit, ...visitorData } = await fpjsClient.getVisitorData()
`

Use getVisitorDataFromCache to directly retrieve responses from cache:

`js
// Checks if request matching given options is present in cache
await fpjsClient.isInCache({ extendedResult: true })

// Returns cached visitor data based on the request options, or undefined if the data is not present in cache
const cachedResult = await fpjsClient.getVisitorDataFromCache({ extendedResult: true })
`

You can also use your custom cache implementation as described below.

$3

The SDK can use a custom cache store implemented inside your application. This is useful when a different data store is more convenient in your environment, such as a hybrid mobile app.

You can provide an object to the cache property of the SDK configuration that implements the following functions. All the functions can return a Promise or a static value.

| Signature | Return type | Description |
| -------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| get(key) | Promise