@fingerprintjs/fingerprintjs-pro-react

Fingerprint Pro React

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.

Table of contents

• Requirements
• Installation
• Getting started
• Linking and tagging information
• Caching strategy
• Error handling
• API Reference
• Support and feedback
• License

Requirements

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

Installation

Using npm:

npm install @fingerprintjs/fingerprintjs-pro-react

Using yarn:

yarn add @fingerprintjs/fingerprintjs-pro-react

Using pnpm:

pnpm 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 Fingerprint Pro Quick Start Guide.

1. Wrap your application (or component) in <FpjsProvider>.

• Set apiKey to your Fingerprint Public API Key.
• Set region if you have chosen a non-global region during registration.
• 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 /*, FingerprintJSPro */ } from '@fingerprintjs/fingerprintjs-pro-react'
import App from './App'

const root = ReactDOM.createRoot(document.getElementById('app'))

root.render(
  <FpjsProvider
    loadOptions={{
      apiKey: 'your-public-api-key',
      // region: 'eu',
      // endpoint: ['metrics.yourwebsite.com', FingerprintJSPro.defaultEndpoint],
      // scriptUrlPattern: ['metrics.yourwebsite.com/agent-path', FingerprintJSPro.defaultScriptUrlPattern],
    }}
  >
    <App />
  </FpjsProvider>
)

2. Use the useVisitorData() hook in your components to identify visitors

// 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 type='email' 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.
• See our Use cases page for open-source real-world examples of using Fingerprint to detect fraud and streamline user experiences.

Linking and tagging information

The visitorId provided by Fingerprint Identification is especially useful when combined with information you already know about your users, for example, account IDs, order IDs, etc. To learn more about various applications of the linkedId and tag, see Linking and tagging information.

Associate the visitor ID with your data using the linkedId or tag parameter of the options object passed into the useVisitorData() hook or the getData function:

// ...

function App() {
  const {
    isLoading,
    error,
    getData
  } = useVisitorData({
    linkedId: "user_1234",
    tag: {
      userAction: "login",
      analyticsId: "UA-5555-1111-1"
    }
  });

// ...

Caching strategy

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 in memory or localStorage. Use none 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 the getData() 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.

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 [e-mail]. 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.

Changelog

2.6.3 (2024-03-21)

Bug Fixes

• review (951860c)
• set initial isLoading according to config.immediate (3194f33)

Build System

• deps: update dependencies to latest version, now using @fingerprintjs/fingerprintjs-pro-spa@1.3.1 (275e234)