@fingerprintjs/fingerprintjs-pro-react

Fingerprint Pro React

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. This package works with Fingerprint Pro, it is not compatible with open-source FingerprintJS. You can learn more about the difference between Fingerprint Pro and open-source FingerprintJS in the official documentation.

Table of contents

• Installation
• Getting started
• Caching strategy
• Error handling
• API Reference
• Support and feedback
• License

Installation

Using npm:

npm install @fingerprintjs/fingerprintjs-pro-react

Using yarn:

yarn add @fingerprintjs/fingerprintjs-pro-react

Getting started

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.

1. 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. Set endpoint and scriptUrlPattern 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>
);

1. 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.

Caching strategy

Fingerprint Pro usage is billed per API call. To reduce API calls, it is a good practice to cache identification results. The SDK uses SessionStorage to cache results by default.

:warning: WARNING If you use data from extendedResult, pay additional attention to caching strategy.

Some fields from the extendedResult (e.g., ip or lastSeenAt) might change over time for the same visitor. If you need to get the latest results, pass {ignoreCache: true} to the getData() function.

Error handling

The getData function throws errors directly from the JS Agent without changing them. See JS Agent error handling for more details.

API Reference

See the full generated API reference.

Support and feedback

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.

License

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