Prove Auth FingerprintJS Integration

A device fingerprinting integration that connects Prove Auth with FingerprintJS for enhanced device identification and fraud prevention.

Overview

This integration enables seamless device fingerprinting within Prove Auth applications by integrating with FingerprintJS Pro. It provides device identification capabilities that enhance security and user experience through persistent device recognition.

Features

• Device Fingerprinting: Advanced browser and device fingerprinting
• Fraud Prevention: Enhanced security through device identification
• Cross-Session Recognition: Persistent device identification across sessions
• TypeScript Support: Full TypeScript definitions included
• Error Handling: Comprehensive error handling for fingerprint collection

Installation

npm install @prove-identity/prove-auth-fingerprint

Prerequisites

• @prove-identity/prove-auth (peer dependency)
• @fingerprintjs/fingerprintjs-pro (automatically installed)
• Valid FingerprintJS Pro API key
• Modern web browser with JavaScript enabled

Usage

Basic Setup

import * as fpJS from '@prove-identity/prove-auth-fingerprintjs';
import { AuthenticatorBuilder } from '@prove-identity/prove-auth';

// Activate the Fingerprint integration
fpJS.activate();

// Build authenticator with device context
const authenticator = new AuthenticatorBuilder()
  .withDeviceContext({
    publicApiKey: 'your-fingerprintjs-api-key',
    buildConfig: BuildConfig.PROD,
  })
  .build();

Device Context Options

interface DeviceContextOptions {
  publicApiKey: string; // FingerprintJS Pro API key
  buildConfig?: BuildConfig; // Environment configuration
  customScriptUrl?: string; // Custom script URL (optional)
  customEndpointUrl?: string; // Custom endpoint URL (optional)
}

API Reference

Methods

initiateFpDataCollection(options: DeviceContextOptions): void

Initializes fingerprint data collection with the provided device context options.

Parameters:

• options - Device context options including API key and configuration

getCollectedFpData(): Promise<Signal>

Retrieves collected fingerprint data.

Returns:

• Promise<Signal> - Resolves to fingerprint data or error information

Signal Interface

interface Signal {
  results?: string; // Sealed fingerprint results
  error?: string; // Error message if collection failed
}

Error Handling

The integration provides detailed error messages for common failure scenarios:

• Missing or invalid API key
• Network connectivity issues
• Browser compatibility problems
• Collection timeouts

Browser Compatibility

• Chrome 60+
• Firefox 55+
• Safari 11+
• Edge 79+

Development

Run npm from the repository root directory using workspaces

Building

npm run build -w integrations/prove-auth-fingerprintjs

Testing

npm test -w integrations/prove-auth-fingerprintjs

Bundling

npm run bundle -w integrations/prove-auth-fingerprintjs

Configuration

Environment-Specific Settings

The integration supports different build configurations:

• BuildConfig.DEV - Development environment
• BuildConfig.PROD - Production environment

Custom Endpoints

You can specify custom script and endpoint URLs for on-premise deployments:

{
  publicApiKey: 'your-api-key',
  customScriptUrl: 'https://your-domain.com/fp-script.js',
  customEndpointUrl: 'https://your-domain.com/fp-endpoint'
}

License

This project is licensed under the Creative Commons Attribution NonCommercial NoDerivs 4.0 International License (CC BY-NC-ND 4.0).

Support

For technical support and documentation, visit:

• Prove Developer Portal
• FingerprintJS Documentation

© 2023-2025 Prove Identity, Inc. All rights reserved.