Fingerprint React

Fingerprint is a device intelligence platform offering industry-leading accuracy. Fingerprint React SDK is an easy way to integrate Fingerprint into your React application. It's also compatible with Next.js and Preact. See application demos in the examples folder.

Table of contents

• Fingerprint React
  • Table of contents
  • Requirements
  • Installation
  • Getting started
    • 1. Wrap your application (or component) in <FingerprintProvider>.
    • 2. Use the useVisitorData() hook in your components to identify visitors
  • Linking and tagging information
  • Error handling
  • API Reference
  • Version support
  • Support and feedback
  • License

Requirements

• React 18 or 19
• 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 subscription or trial, it is not compatible with the open-source FingerprintJS. See our documentation to learn more about the differences between Fingerprint and the open-source FingerprintJS.

Installation

Using npm:

npm install @fingerprint/react

Using yarn:

yarn add @fingerprint/react

Using pnpm:

pnpm add @fingerprint/react

Getting started

In order to identify visitors, you'll need a Fingerprint account (you can sign up for free). To get your API key and get started, see the Fingerprint Quick Start Guide.

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

• Set apiKey to your Fingerprint Public API Key.
• Set region if you have chosen a non-global region during registration.
• Set endpoints if you are using one of our proxy integrations to increase accuracy and effectiveness of visitor identification.
• You can use all the start options available in the JavaScript agent start() function.
• Caching is disabled by default. To enable caching, pass the JavaScript agent cache start option.

// src/index.js
import React from 'react'
import ReactDOM from 'react-dom/client'
import { FingerprintProvider } from '@fingerprint/react'
import App from './App'

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

// <FingerprintProvider /> supports the same options as `start()` function.
root.render(
  <FingerprintProvider
    apiKey='PUBLIC_API_KEY'
    cache={{ storage: 'sessionStorage', duration: 3600 }}
  >
    <App />
  </FingerprintProvider>
)

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

// src/App.js
import React from 'react'
import { useVisitorData } from '@fingerprint/react'

function App() {
  const { isLoading, error, isFetched, data } = useVisitorData()

  if (isLoading) {
    return <div>Loading...</div>
  }
  if (error) {
    return <div>An error occurred: {error.message}</div>
  }

  if (isFetched) {
    return <div>Welcome {data.visitor_id}!</div>
  }
  
  return null
}

export default App

The useVisitorData hook also returns a getData method you can use to make an API call on command.

Both useVisitorData and getData accept all the get options available in the JavaScript agent get function.

The returned v4 visitor data uses raw response field names in snake_case, for example visitor_id and event_id.

// src/App.js
import React, { useState } from 'react'
import { useVisitorData } from '@fingerprint/react'

function App() {
  const { isLoading, error, getData } = useVisitorData(
    { 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.visitor_id)
            })
            .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

• You can pass { immediate: false } to disable automatic identification and call getData manually instead.
• By default ({ immediate: true }), the hook automatically identifies the visitor after mounting and whenever its request options change. Changing immediate from false to true also starts an identification request with the latest options.
• 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 visitor ID 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 tags, see Linking and tagging information.

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

// ...
function App() {
  const { isLoading, error, getData } = useVisitorData({
    linkedId: 'user_1234',
    tags: {
      userAction: 'login',
      analyticsId: 'UA-5555-1111-1',
    },
  })
}
// ...

[!NOTE] The tag option is deprecated in favor of tags. tag still works, but if both are provided, tags takes precedence.

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.

Version support

Support and feedback

To ask questions or provide feedback, use Issues. If you need private support, please email us at [email protected].

License

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