Fingerprint is a device intelligence platform offering 99.5% accurate visitor identification. Fingerprint Pro React SDK is an easy way to integrate Fingerprint Pro into your React application. It's also compatible with Next.js and Preact. See application demos in the examples folder.
- Requirements
- Installation
- Getting started
- Caching strategy
- Error handling
- API Reference
- Support and feedback
- License
- React 18 or higher
- For Preact users: Preact 10.3 or higher
- For Next.js users: Next.js 13.1 or higher
- For Typescript users: Typescript 4.8 or higher
Note: This package 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.
Using npm:
npm install @fingerprintjs/fingerprintjs-pro-react
Using yarn:
yarn add @fingerprintjs/fingerprintjs-pro-react
Using pnpm:
pnpm add @fingerprintjs/fingerprintjs-pro-react
In order to identify visitors, you'll need a Fingerprint Pro account (you can sign up for free). To get your API key and get started, see the official Fingerprint Pro documentation.
- Wrap your application (or component) in
FpjsProvider
. You can specify multiple configuration options. Set a region if you have chosen a non-global region during registration. See Regions in our documentation. Setendpoint
andscriptUrlPattern
if you are using one of our proxy integrations to increase accuracy and effectiveness of visitor identification.
// src/index.js
import React from 'react';
import ReactDOM from 'react-dom/client';
import { FpjsProvider, /* defaultEndpoint, defaultScriptUrlPattern */ } from '@fingerprintjs/fingerprintjs-pro-react';
import App from './App';
const root = ReactDOM.createRoot(document.getElementById('app'))
root.render(
<FpjsProvider
loadOptions={{
apiKey: 'your-fpjs-public-api-key',
// region: 'eu',
// endpoint: ['metrics.yourwebsite.com', defaultEndpoint],
// scriptUrlPattern: ['metrics.yourwebsite.com/agent-path', defaultScriptUrlPattern],
}}
>
<App />
</FpjsProvider>
);
- Use the
useVisitorData
hook in your components to identify visitors and get the result data.
// src/App.js
import React from 'react';
import { useVisitorData } from '@fingerprintjs/fingerprintjs-pro-react'
function App() {
const {
isLoading,
error,
data,
} = useVisitorData();
if (isLoading) {
return <div>Loading...</div>;
}
if (error) {
return <div>An error occured: {error.message}</div>;
}
if (data) {
// Perform some logic based on the visitor data
return (
<div>
Welcome {data.visitorFound ? 'back' : ''}, {data.visitorId}!
</div>
);
} else {
return null;
}
}
export default App;
The useVisitorData
hook also returns a getData
method you can use to make an API call on command.
// src/App.js
import React, { useState } from "react";
import { useVisitorData } from "@fingerprintjs/fingerprintjs-pro-react";
function App() {
const {
isLoading,
error,
getData
} = useVisitorData({tag: "subscription-form"}, { immediate: false });
const [email, setEmail] = useState("");
if (isLoading) {
return <div>Loading...</div>;
}
if (error) {
return <div>An error occurred: {error.message}</div>;
}
return (
<div>
<form
onSubmit={(e) => {
e.preventDefault();
getData()
.then((data) => {
// Do something with the visitor data, for example,
// append visitor data to the form data to send to your server
console.log(data)
})
.catch((error) => {
// Handle error
})
}}
>
<label htmlFor="email">Email:</label>
<input
id="email"
type="email"
name="email"
required
value={email}
onChange={(e) => setEmail(e.currentTarget.value)}
/>
<button type="submit">Subscribe</button>
</form>
</div>
);
}
export default App;
See the full code example in the examples folder.
Fingerprint Pro usage is billed per API call. To avoid unnecessary API calls, it is a good practice to cache identification results. By default, the SDK uses sessionStorage
to cache results.
- Specify the
cacheLocation
prop on<FpjsProvider>
to instead store results inmemory
orlocalStorage
. Usenone
to disable caching completely. - Specify the
cache
prop on<FpjsProvider>
to use your custom cache implementation instead. For more details, see Creating a custom cache in the Fingerprint Pro SPA repository (a lower-level Fingerprint library used by this SDK). - Pass
{ignoreCache: true}
to thegetData()
function to ignore cached results for that specific API call.
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. Use getData({ ignoreCache: true })
to fetch the latest identification results.
The getData
function throws errors directly from the JS Agent without changing them. See JS Agent error handling for more details.
See the full generated API reference.
To ask questions or provide feedback, use Issues. If you need private support, please email us at oss-support@fingerprint.com
. If you'd like to have a similar React wrapper for the open-source FingerprintJS, consider creating an issue in the main FingerprintJS repository.
This project is licensed under the MIT license. See the LICENSE file for more info.