react-native-thumbmark

Thumbmark device fingerprinting library for React Native. Generate unique device identifiers and collect detailed device fingerprints on iOS and Android.

Features

• 🔐 Device ID: SHA-256 hash-based unique device identifier
• 🆔 Persistent ID: UUID stored in secure storage (survives app reinstalls)
• 📊 Detailed Fingerprint: Comprehensive device information (processor, memory, sensors, etc.)
• 📱 Cross-platform: iOS and Android support
• ⚡ New & Old Architecture: Compatible with both React Native architectures
• 🔒 Secure Storage: iCloud Keychain (iOS) and SharedPreferences with backup (Android)

Installation

npm install react-native-thumbmark
# or
yarn add react-native-thumbmark

iOS

cd ios && pod install

Android

No additional steps required. Gradle will handle dependencies automatically.

Usage

import { getDeviceId, getPersistentId, getFingerprint } from 'react-native-thumbmark';

// Get device ID (SHA-256 hash of device fingerprint)
// This ID may change if device parameters change
const deviceId = await getDeviceId();
console.log(deviceId); // "a1b2c3d4e5f6..."

// Get persistent ID (UUID stored in secure storage)
// This ID never changes and survives app reinstalls
const persistentId = await getPersistentId();
console.log(persistentId); // "550e8400-e29b-41d4-a716-446655440000"

// Get persistent ID with 30-day expiry
const persistentIdWithExpiry = await getPersistentId(30);

// Get detailed device fingerprint
const fingerprint = await getFingerprint();
console.log(fingerprint);
// {
//   device: { model: "iPhone 15", ... },
//   processor: { count: 6, ... },
//   memory: { total: "8 GB", ... },
//   captureDevices: [...],
//   accessibility: {...},
//   locality: {...},
//   communication: {...}
// }

API Reference

getDeviceId()

Returns a SHA-256 hash of the device fingerprint.

Returns: Promise<string>

Note: This ID is computed from device parameters and may change if hardware or system settings change.

getPersistentId(expiryDays?)

Returns a UUID stored in secure storage that persists across app reinstalls.

Parameters:

• expiryDays (optional): Number of days until the ID expires. If not provided, the ID never expires.

Returns: Promise<string>

Storage:

• iOS: iCloud Keychain (survives app reinstall and factory reset if iCloud is enabled)
• Android: SharedPreferences with backup (survives app reinstall if backup is enabled)

getFingerprint()

Returns detailed device information including processor, memory, sensors, and more.

Returns: Promise<object>

Example response:

{
  device: {
    model: "iPhone 15",
    systemName: "iOS",
    systemVersion: "17.0",
    // ...
  },
  processor: {
    count: 6,
    // ...
  },
  memory: {
    total: "8 GB",
    // ...
  },
  captureDevices: [...],
  accessibility: {...},
  locality: {...},
  communication: {...}
}

Architecture Support

This library supports both React Native's Old Architecture (Bridge) and New Architecture (TurboModules/Fabric). It automatically detects which architecture is enabled and uses the appropriate implementation.

Example App

See the example folder for a complete working example.

# Run iOS example
cd example && yarn ios

# Run Android example
cd example && yarn android

Platform-Specific Notes

iOS

• Requires iOS 13.0 or higher
• Uses SimpleKeychain for secure storage
• Persistent ID is stored in iCloud Keychain and syncs across devices

Android

• Requires Android API 21 (Lollipop) or higher
• Uses SharedPreferences with allowBackup for data persistence
• Persistent ID survives app reinstalls when Android backup is enabled

Privacy & Permissions

This library collects device information for fingerprinting purposes. Make sure to:

1. Disclose this in your app's privacy policy
2. Comply with GDPR, CCPA, and other privacy regulations
3. Obtain user consent where required

The library does NOT:

• Collect personally identifiable information (PII)
• Send data to external servers
• Require special permissions (all data is from public APIs)

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Credits

This library integrates code from the following open-source projects:

Thumbmark Libraries

• thumbmark-swift - iOS device fingerprinting library (MIT License)
• thumbmark-android - Android device fingerprinting library (MIT License)

Special thanks to the Thumbmark team for creating these excellent device fingerprinting libraries.

Dependencies

• SimpleKeychain by Auth0 - iOS keychain wrapper (MIT License)

Made with create-react-native-library