Migrating FingerprintJS v3 to v5

This guide shows how to migrate your code from FingerprintJS version 3 to version 5. The API and the installations methods are almost the same in both version.

Installation

The migration process depends on the way you install the library.

CDN

Change the version number in the URL from 3 to 5. For example:

- https://openfpcdn.io/fingerprintjs/v3/iife.min.js
+ https://openfpcdn.io/fingerprintjs/v5/iife.min.js

NPM or Yarn

Update the package version:

npm install @fingerprintjs/fingerprintjs
# or
yarn add @fingerprintjs/fingerprintjs

API

Entropy source unexpected error handling

If you don't handle errors in components field of get() result, skip this section.

In version 3 unexpected entropy source errors were coerced to a { message: any } object, so that the error field of a component object is always truthy in case of unexpected error.

In version 5 the caught error is put into the error field as is. The presence of error should be checked using the 'error' in component syntax:

- if (component.error) {
+ if ('error' in component) {
    console.log('Unexpected error in the component', component.error)
  }

TypeScript supports type-guarding using in keyword since version 4.9, so the above code snippet works in TypeScript just fine.

This example shows the get() result difference in case when the error is a falsy value, which is very unlikely:

const result = {
  visitorId: '...',
  components: {
    failedComponent: {
-     error: { message: '' },
+     error: '',
      duration: 10,
    },
  },
  // ...
}

How to update without losing the identifiers

The process is the same as for minor version update. See the version policy guide.