Fingerprint is a device intelligence platform offering industry-leading accuracy. Fingerprint Pro React Native SDK is an easy way to integrate Fingerprint Pro into your React Native application to call the native Fingerprint Pro libraries (Android and iOS) and identify devices.
- Fingerprint Pro React Native
-
React Native 0.80 or higher is supported (New Architecture only)
-
Expo 54.0.0 or higher is supported
-
Android 7.0 (API level 24+) or higher
-
iOS 15.1+/tvOS 15.1+, Swift 5.9 or higher (stable releases)
-
Fingerprint Pro request filtering is not supported right now. Allowed and forbidden origins cannot be used.
Install the package using your favorite package manager:
-
NPM:
npm install @fingerprint/react-native --save
-
Yarn:
yarn add @fingerprint/react-native
-
PNPM:
pnpm add @fingerprint/react-native
ℹ️ Our SDK cannot be used in Expo Go because it requires custom native code.
Web support
To use the SDK on the web, install the peer dependency with your preferred package manager:-
NPM:
npm install @fingerprint/agent --save
-
Yarn:
yarn add @fingerprint/agent
-
PNPM:
pnpm add @fingerprint/agent
Then, use the SDK as you would with the native version.
{
"expo": {
"plugins": [
"@fingerprint/react-native"
]
}
}npx expo prebuild --cleanFor Android:
npx expo run:androidFor iOS:
npx expo run:ioscd ios && pod installAdd 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:
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
repositories {
google()
mavenCentral()
maven {
url("https://maven.fpregistry.io/releases") // Add this
}
}
}To identify visitors, you need a Fingerprint Pro account (you can sign up for free).
- Go to the Fingerprint Pro dashboard.
- Open App Settings > API Keys to find your Public API key.
Configure the SDK by wrapping your application in FingerprintProvider.
⚠️ Important: Applications should create only one client across the entire app, either throughFingerprintProvideror through the API client (start()). If you create another client, it will overwrite the underlying native client of the first one.
// 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={'your-fpjs-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.
// 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>VisitorId: {data?.visitor_id}</Text>
<Text>Full visitor data:</Text>
<Text>{error ? error.message : JSON.stringify(data, null, 2)}</Text>
</>
)}
</View>
</SafeAreaView>
)
}ℹ️ By default the hook does not fetch automatically. Pass
useVisitorData({ immediate: true })to identify on mount and whenever the request options change.
⚠️ Caching is available only on web and is disabled by default. To enable caching on web, pass the JavaScript agent cache option:<FingerprintProvider apiKey={'your-fpjs-public-api-key'} region={'eu'} web={{ cache: { storage: 'sessionStorage', duration: 'optimize-cost' } }}> <App /> </FingerprintProvider>
Create a client with start() and call get():
⚠️ Important: Applications should create only one client across the entire app, either throughFingerprintProvideror through the API client (start()). If you create another client, it will overwrite the underlying native client of the first one.
import React, { useEffect } from 'react';
import { start } from '@fingerprint/react-native';
// ...
useEffect(() => {
async function getVisitorInfo() {
try {
const fp = start({ apiKey: 'PUBLIC_API_KEY', region: 'eu' }); // Region may be 'us', 'eu', or 'ap'
const result = await fp.get();
console.log(result.visitor_id, result.event_id);
} catch (e) {
console.error('Error: ', e);
}
}
getVisitorInfo();
}, []);Inside the React tree you can also get the same client from context with the useFingerprint() hook:
import { useFingerprint } from '@fingerprint/react-native';
const fp = useFingerprint();
const result = await fp.get({ linkedId: 'user_1234' });The response is a flat, snake_case object that matches the Fingerprint Server API v4 and the JS agent.
interface FingerprintResponse {
visitor_id?: string // `undefined` if [zero-trust-mode](https://docs.fingerprint.com/docs/zero-trust-mode) is enabled
event_id: string
suspect_score?: number // present only when Smart Signals are enabled
sealed_result: string | null // base64 sealed result, or null when unavailable
cache_hit?: boolean // Used only on web, on native always set to `undefined`
}Every failure is thrown as a single FingerprintError carrying a machine-friendly code (e.g.
too_many_requests) and a resolution-oriented message:
import { isFingerprintError } from '@fingerprint/react-native';
try {
await fp.get();
} catch (error) {
if (isFingerprintError(error) && error.code === 'too_many_requests') {
// handle rate limiting
}
}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.
Pass tags and linkedId in a single options object:
const tags = {
userAction: 'login',
analyticsId: 'UA-5555-1111-1'
};
const linkedId = 'user_1234';
// Using hooks
const { getData } = useVisitorData();
const visitorData = await getData({ tags, linkedId });
// Using the client
const fp = start({ apiKey: 'PUBLIC_API_KEY' });
const visitor = await fp.get({ tags, linkedId });Proximity detection is a complementary, location-based signal available only on mobile platforms. You can find more information in Android SDK documentation or in iOS SDK documentation.
Platform-only options are grouped under android and ios. The Fingerprint SDK will only collect
location data if allowUseOfLocationData is set to true.
return (
<FingerprintProvider apiKey={PUBLIC_API_KEY} android={{ allowUseOfLocationData: true }} ios={{ allowUseOfLocationData: true }}>
<App />
</FingerprintProvider>
)For the Android platform it's possible to configure the location retrieval timeout by setting the locationTimeoutMillis option to a desired value. By default, it's set to 5 seconds.
The SDK will delay identification up to the specified timeout to collect the device location. If it cannot collect the location information within the specified time, identification continues without location information.
return (
<FingerprintProvider apiKey={PUBLIC_API_KEY} android={{ allowUseOfLocationData: true, locationTimeoutMillis: 10000 }}>
<App />
</FingerprintProvider>
)See the full generated API Reference.
To report problems, ask questions or provide feedback, please
use Issues. If you need private support,
please email us at oss-support@fingerprint.com.
This project is licensed under the MIT license.