Overview

Fingerprint React Native is an official open-source library for projects written in React Native for iOS and Android platforms. This library allows developers to use Fingerprint capabilities in the React Native context. View our React Native quickstart for a step-by-step guide to get started.

Upgrading from SDK v3? See the migration guide for a full list of breaking changes, including the package rename from @fingerprintjs/fingerprintjs-pro-react-native to @fingerprint/react-native.

Requirements

The React Native SDK uses the Android and iOS SDKs under the hood, and it requires React Native 0.80, so the effective minimum versions are:

React Native 0.80 or higher, with the New Architecture enabled. The Old Architecture isn’t supported. This floor comes from the SDK’s use of React Native’s Strict TypeScript API.
Android 7.0 (API level 24+) or higher, as required by React Native 0.80
iOS 15.1 or higher (or tvOS 15 or higher), Swift 5.9 or higher
Expo SDK 54 or higher. The SDK isn’t usable in Expo Go because it includes custom native code; use a development build instead.

How to install

1. Install the package using your favorite package manager:

npm install @fingerprint/react-native --save

yarn add @fingerprint/react-native

pnpm add @fingerprint/react-native

2. Configure dependencies:

Expo setup

Add the config plugin to your app.json or app.config.js:

app.json

{
  "expo": {
    "plugins": ["@fingerprint/react-native"]
  }
}

Rebuild your native projects:

npx expo prebuild --clean

Because the SDK includes custom native code, it doesn’t work in Expo Go. Use npx expo run:ios/run:android or an EAS development build.

Bare React Native setup

Configure iOS dependencies (if developing on iOS)

cd ios && pod install

Configure Android dependencies (if developing on Android)

Add the repositories to your Gradle configuration file. The location for these additions depends on your project’s structure and the Gradle version you’re using: You likely manage repositories in the dependencyResolutionManagement block in {rootDir}/android/settings.gradle. Add the Maven repositories in this block:

Groovy

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
  repositories {
    google()
    mavenCentral()
    maven {
      url("https://maven.fpregistry.io/releases") // Add this
    }
  }
}

3. SPM support (experimental)

On React Native 0.87 and higher, you can link iOS dependencies with Swift Package Manager instead of CocoaPods:

cd ios && npx react-native spm --deintegrate

SPM support is experimental. If you hit issues, fall back to pod install.

Web support

If your app also targets web (for example with React Native Web), install @fingerprint/agent as an optional peer dependency:

npm install @fingerprint/agent@^4.1.3 --save

Usage

Configure the SDK by wrapping your application in FingerprintProvider.

JavaScript

// src/index.js
import React from 'react';
import { AppRegistry } from 'react-native';
import { FingerprintProvider } from '@fingerprint/react-native';
import App from './App';
import { name as appName } from './app.json';

const WrappedApp = () => (
  <FingerprintProvider apiKey={'PUBLIC_API_KEY'} region={'eu'}>
    <App />
  </FingerprintProvider>
)

AppRegistry.registerComponent(appName, () => WrappedApp);

Use the useVisitorData hook in your components to perform visitor identification and get the data. getData always throws on error, and immediate defaults to false so the SDK doesn’t fetch eagerly on mount (native platforms don’t cache results, so eager fetches cost API calls).

JavaScript

// src/App.js
import React from 'react'
import {Button, SafeAreaView, Text, View} from 'react-native'
import {useVisitorData} from '@fingerprint/react-native'

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

  return (
    <SafeAreaView>
      <View style={{ margin: 8 }}>
        <Button title='Reload data' onPress={() => getData().catch(() => {})} />
        {isLoading ? (
          <Text>Loading...</Text>
        ) : (
          <>
            <Text>Visitor ID: {isFetched ? data?.visitor_id : undefined}</Text>
            <Text>Full visitor data:</Text>
            <Text>{error ? error.message : JSON.stringify(data, null, 2)}</Text>
          </>
        )}
      </View>
    </SafeAreaView>
  )
}

API client

To integrate outside of a React component, call start() once to create a client. start() returns the client synchronously; only get() is asynchronous.

JavaScript

import { start } from '@fingerprint/react-native';

const fp = start({ apiKey: 'PUBLIC_API_KEY', region: 'eu' });
const data = await fp.get({ tags: { action: 'login' } });

console.log(data.visitor_id, data.event_id);

useFingerprint

Use useFingerprint() inside FingerprintProvider to read the same client from context, for example to call get() from an event handler instead of relying on the hook’s automatic fetch:

JavaScript

import { useFingerprint } from '@fingerprint/react-native';

function LoginButton() {
  const fp = useFingerprint();

  const handleLogin = async () => {
    const data = await fp.get({ tags: { action: 'login' } });
    console.log(data.visitor_id);
  };

  return <Button title="Log in" onPress={handleLogin} />;
}

Response format

useVisitorData and get() resolve with a flat object that matches the Server API v4 event format:

interface FingerprintResponse {
  visitor_id?: string; // `undefined` if zero-trust mode is enabled
  event_id: string;
  suspect_score?: number; // only present when Smart Signals are enabled
  sealed_result: string | null;
  cache_hit?: boolean; // web only, set when caching is configured; always undefined on native platforms
}

The SDK no longer supports extendedResponseFormat or the nested extended fields (ipLocation, firstSeenAt, osName, and similar); it always returns this flat format. Use IP Geolocation and the other Smart Signals for the data those fields used to carry.

Error handling

All identification failures are instances of FingerprintError, with name, code, and event_id fields. Use the isFingerprintError type guard to identify them, and discriminate behavior on error.code:

JavaScript

import { isFingerprintError } from '@fingerprint/react-native';

try {
  const data = await getData();
} catch (error) {
  if (isFingerprintError(error)) {
    console.log(error.code, error.event_id);
  }
}

code is a string union that groups into:

Server / API v4 error codes, returned by the Fingerprint API itself
Native client-side error codes, raised by the underlying Android or iOS SDK
Web client-side error codes, raised by the underlying @fingerprint/agent client

Treat code as open to unknown strings; handle the codes you care about and fall back to generic handling for the rest.

Linking and tagging

Pass tags, linkedId, and timeout together as a single options object:

JavaScript

const data = await getData({
  tags: { action: 'checkout' },
  linkedId: 'user-1234',
  timeout: 5000,
});

Proximity detection

Location-based options are grouped by platform:

JavaScript

<FingerprintProvider
  apiKey="PUBLIC_API_KEY"
  region="eu"
  android={{ allowUseOfLocationData: true, locationTimeoutMillis: 2000 }}
  ios={{ allowUseOfLocationData: true }}
>
  <App />
</FingerprintProvider>

Caching

Caching is web-only and disabled by default. Enable it via the web option:

JavaScript

<FingerprintProvider
  apiKey="PUBLIC_API_KEY"
  region="eu"
  web={{ cache: { storage: 'sessionStorage', duration: 3600 } }}
>
  <App />
</FingerprintProvider>

Documentation

You can find the full documentation in the official GitHub repository.

Limitations

Fingerprint request filtering is not supported right now. Allowed and forbidden origins cannot be used.

Understanding Fingerprint

Identify browsers

Identify mobile devices

AI

Rules Engine and Flow (Beta)

Protect your implementation

Integrate with your server

Integrate Smart Signals

Device reputation network

Tips and advanced guides

Platform updates

Resources

Legal

Requirements

How to install

1. Install the package using your favorite package manager:

2. Configure dependencies:

Expo setup

Bare React Native setup

3. SPM support (experimental)

Web support

Usage

API client

useFingerprint

Response format

Error handling

Linking and tagging

Proximity detection

Caching

Documentation

Limitations

​Requirements

​How to install

​1. Install the package using your favorite package manager:

​2. Configure dependencies:

​Expo setup

​Bare React Native setup

​3. SPM support (experimental)

​Web support

​Usage

​API client

​useFingerprint

​Response format

​Error handling

​Linking and tagging

​Proximity detection

​Caching

​Documentation

​Limitations

Requirements

How to install

1. Install the package using your favorite package manager:

2. Configure dependencies:

Expo setup

Bare React Native setup

3. SPM support (experimental)

Web support

Usage

API client

useFingerprint

Response format

Error handling

Linking and tagging

Proximity detection

Caching

Documentation

Limitations