@fingerprintjs/fingerprintjs-pro-spa

Fingerprint Pro SPA

This library is designed to be used in single-page-application framework wrappers for the Fingerprint Pro JavaScript Agent. It has multiple built-in caching mechanisms with recommended default settings.

If you just need the Fingerprint Pro JS agent, you can use it directly, without this wrapper. If you're looking for a framework-specific integration, we have dedicated SDKs for React (including Next, Preact), Vue, Svelte and Angular.

This SDK works with Fingerprint Pro, it will not work with the open-source FingerprintJS version! Learn more about the difference between Pro and OSS. If you'd like to have a similar SPA wrapper for the OSS version of FingerprintJS, consider raising an issue in our issue tracker.

Table of Contents

• Documentation
• Installation
• Getting Started
• Support + Feedback
• License

Documentation

This library uses Fingerprint Pro under the hood.

• To learn more about Fingerprint Pro read our product documentation.
• To learn more about this SDK, there is a Typedoc-generated SDK Reference available.

Installation

Using npm:

npm install @fingerprintjs/fingerprintjs-pro-spa

Using yarn:

yarn add @fingerprintjs/fingerprintjs-pro-spa

Getting Started

Fingerprint Pro public API key

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

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

Creating the client

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.

import { 
  FpjsClient,
  // defaultEndpoint,
  // defaultScriptUrlPattern
} from '@fingerprintjs/fingerprintjs-pro-spa';

// It can receive multiple parameters but the only required one is `loadOptions`, 
// which contains the public API key
const fpjsClient = new FpjsClient({
  loadOptions: {
    apiKey: "<PUBLIC_API_KEY>",
    // endpoint: ["<CUSTOM_ENDPOINT>", defaultEndpoint],
    // scriptUrlPattern: ["<CUSTOM_SCRIPT_URL>", defaultScriptUrlPattern],
    // region: "eu"
  }
});

You can learn more about different load options here in the JS Agent documentation.

1 - Init the JS agent

Before you start making identification requests to the Fingerprint Pro API, you need to initialize the JS Agent to allow it to gather browser signals. Make sure the initialization has been completed before calling the getVisitorData method to avoid errors.

// with async/await
await fpjsClient.init()
const visitorData = await fpjsClient.getVisitorData()

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

2 - Calling an API

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

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

// 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
})

Caching

The SDK can cache the visitor data in session storage (default), in local storage, or in memory. You can specify the cacheLocation option when creating the Fpjs client.

const fpjsClient = new FpjsClient({
  loadOptions: {
    apiKey: "your-fpjs-public-api-key"
  },
  cacheLocation: 'localstorage'
});

Or if you are using TypeScript:

const fpjsClient = new FpjsClient({
  loadOptions: {
    apiKey: "your-fpjs-public-api-key"
  },
  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.

Creating a custom cache

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 or object	Returns the item from the cache with the specified key, or undefined if it was not found
set(key: string, object: any)	Promise or void	Sets an item into the cache
remove(key)	Promise or void	Removes a single item from the cache at the specified key, or no-op if the item was not found
allKeys()	Promise<string[]> or string []	Returns the list of all keys. By default, the keys we use are prefixed with @fpjs@client@ but you can pass your own custom prefix as an option when you create the FpjsClient

Note: The cache property takes priority over cacheLocation if both are set. A warning is displayed in the console if that happens.

We export the internal InMemoryCache, LocalStorageCache, SessionStorageCache, and CacheStub implementations, so you can wrap your custom cache around these implementations if you wish.

Cache time

Use the cacheTimeInSeconds client constructor option to set a custom cache time. To ensure high identification accuracy we recommend not to cache visitors data for longer than 24 hours. If you pass a value higher than 86400 (60 * 60 * 24), the FpjsClient constructor will throw an error.

Support + Feedback

For support or to provide feedback, please use Issues.

License

This project is licensed under the MIT license. See the LICENSE file for more information.

Changelog

1.1.1 (2023-09-12)

Bug Fixes

• we can pass custom JS Agent to the SPA package now (24cc153)

Documentation

• README: add fallback endpoints and polish readme (1bd0cbf)