Skip to content

Latest commit

 

History

History
152 lines (113 loc) · 4.76 KB

v1_v4.md

File metadata and controls

152 lines (113 loc) · 4.76 KB
Raw

Migrating FingerprintJS v1 to v4

This guide shows how to migrate your code from FingerprintJS version 1 to version 4.

License

Please note that our licensing terms for v4 has changed. The table below indicates the different use-cases that shall require a commercial license to be purchased.

Before license change (versions 3.x and lower) After license change (versions 4.x and higher)
License MIT BSL 1.1
Use FingerprintJS for research, explorative and all other non-commercial purposes ✅ ✅
Fork FingerprintJS repository for production ✅ ❌ (requires a commercial license to be purchased)
Use FingerprintJS in production ✅ ❌ (requires a commercial license to be purchased)

To purchase a license for uses not authorized by BSL, please contact us at [email protected].

Browser support

The support of Internet Explorer and some other browsers has been dropped. See the list of supported browsers in the browser support guide.

Installation

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

CDN

Use the new URL: https://openfpcdn.io/fingerprintjs/v4/iife.min.js

Bower

Bower support is dropped, choose another installation method.

NPM or Yarn

Change the package name:

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

The new version sends HTTP requests to collect usage statistics, they can be disabled. See this page for more details.

Remove the type declaration package. You don't need it because the type declaration is embedded into the main package in v4:

npm remove @types/fingerprintjs2
# or
yarn remove @types/fingerprintjs2

Initialization

Instead of creating a new Fingerprint2 object, you must call FingerprintJS.load(). This function returns a promise that resolves with an agent object. The get method of the agent returns a promise instead of invoking a callback:

- const fp = new Fingerprint2()
- fp.get(function(visitorId, components) {
+ const fpPromise = FingerprintJS.load()
+ fpPromise
+   .then(fp => fp.get()){
+   .then(({ visitorId, components }) => {
      // Handle the result
    })

The format of raw components is different:

console.log(components)

- [
-   { key: 'component1', value: 'Some value' },
-   { key: 'component2', value: ['other', 'value'] },
- ]
+ {
+   component1: { value: 'Some value', duration: 4 },
+   component2: { value: ['other', 'value'], duration: 2 },
+ }

Customization

Version 4 has no options for customization, it provides a good built-in setup. Nevertheless, you can exclude built-in entropy components and add custom entropy components manually. See the extending guide to learn more.

How to update without losing the identifiers

The identifiers produced by version 4 don't match the identifiers produced by version 1. If this is an issue for you, you can implement the following strategy.

Install version 4 together with version 1:

<script src="https://cdn.jsdelivr.net/npm/fingerprintjs2@1/dist/fingerprint2.min.js"></script>
<script src="https://openfpcdn.io/fingerprintjs/v4/iife.min.js"></script>

When you need the visitor identifier, get identifiers from both versions:

Promise.all([
  new Promise(resolve => {
    new Fingerprint2().get((visitorId, components) => {
      resolve({ visitorId, components })
    })
  }),
  FingerprintJS.load().then(fp => fp.get())
]).then(([v1Result, v4Result]) => {
  // Handle both the results. For example, send to your server.
  return fetch(
    '/visitor'
      + `?fingerprintV1=${encodeURIComponent(v1Result.visitorId)}`
      + `&fingerprintV4=${encodeURIComponent(v4Result.visitorId)}`
  )
})

Make your server search using both the identifiers. Save the version 4 identifier:

-- Getting the visitor
SELECT * FROM visitors
WHERE
  fingerprintV1 = :fingerprintV1 OR
  fingerprintV4 = :fingerprintV4;

-- Update the visitor identifier
-- to switch to the fingerprint version 4
UPDATE visitors
SET fingerprintV4 = :fingerprintV4
WHERE fingerprintV1 = :fingerprintV1;

-- Saving a new visitor
INSERT INTO visitors (..., fingerprintV4)
VALUES (..., :fingerprintV4);

Later, when you get many enough identifiers of the version 4, remove the version 1 library and its identifiers.

The version 4 fingerprints may change after updating to a new major version, so you should extend this strategy to minor sub-versions of version 4 too.