dprintjs/README.md

Generate unique device fingerprints using browser characteristics

# dPrintJs

A lightweight, framework-agnostic browser fingerprinting library that generates unique device identifiers. It uses multiple browser characteristics to create either short (8 characters) or long (64 characters) fingerprints that remain consistent for the same device.

## Features

- 🔒 Privacy-focused device fingerprinting
- 🎯 Consistent device identification
- 🔄 Short (8 chars) and long (64 chars) fingerprint formats
- 🛠 Framework agnostic (works with React, Vue, Angular, or vanilla JS)
- ⚡ Lightweight with zero dependencies
- 🎨 Configurable components (Canvas, Audio, WebGL)
- 🔐 Optional salt for additional uniqueness
- 💪 TypeScript support

## Installation

```bash
npm install dprintjs
# or
yarn add dprintjs
# or
pnpm add dprintjs
```

## Quick Start

```javascript
import { dPrintId } from 'dprintjs';

// Get instance
const fingerprint = dPrintId.getInstance();

// Generate short fingerprint (8 characters)
const shortId = await fingerprint.generateFingerprint();
// Example output: "k7lm9n2p"

// Generate long fingerprint (64 characters)
const longId = await fingerprint.generateFingerprint({ format: 'long' });
// Example output: "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92"
```

## Framework Examples

### React

```tsx
import { useEffect, useState } from 'react';
import { dPrintId } from 'dprintjs';

function App() {
  const [deviceId, setDeviceId] = useState('');

  useEffect(() => {
    const getFingerprint = async () => {
      const fingerprint = dPrintId.getInstance();
      const id = await fingerprint.generateFingerprint();
      setDeviceId(id);
    };
    getFingerprint();
  }, []);

  return <div>Device ID: {deviceId}</div>;
}
```

### Vue

```vue
<script setup>
import { ref, onMounted } from 'vue';
import { dPrintId } from 'dprintjs';

const deviceId = ref('');

onMounted(async () => {
  const fingerprint = dPrintId.getInstance();
  deviceId.value = await fingerprint.generateFingerprint();
});
</script>

<template>
  <div>Device ID: {{ deviceId }}</div>
</template>
```

### Angular

```typescript
import { Component, OnInit } from '@angular/core';
import { dPrintId } from 'dprintjs';

@Component({
  selector: 'app-root',
  template: '<div>Device ID: {{deviceId}}</div>'
})
export class AppComponent implements OnInit {
  deviceId = '';

  async ngOnInit() {
    const fingerprint = dPrintId.getInstance();
    this.deviceId = await fingerprint.generateFingerprint();
  }
}
```

### Vanilla JavaScript

```html
<script type="module">
  import { dPrintId } from 'dprintjs';

  async function init() {
    const fingerprint = dPrintId.getInstance();
    const deviceId = await fingerprint.generateFingerprint();
    document.getElementById('device-id').textContent = deviceId;
  }

  init();
</script>

<div id="device-id"></div>
```

## API Reference

### FingerprintOptions

```typescript
interface FingerprintOptions {
  format?: 'short' | 'long';     // Output format (default: 'short')
  includeCanvas?: boolean;       // Use canvas fingerprinting (default: true)
  includeAudio?: boolean;        // Use audio fingerprinting (default: true)
  includeWebGL?: boolean;        // Use WebGL fingerprinting (default: true)
  salt?: string;                 // Additional salt for uniqueness
}
```

### Methods

#### `dPrintId.getInstance()`
Returns the singleton instance of the dPrintId.

#### `generateFingerprint(options?: FingerprintOptions): Promise<string>`
Generates a device fingerprint based on the provided options.

## Examples

### Basic Usage
```javascript
const fingerprint = dPrintId.getInstance();
const deviceId = await fingerprint.generateFingerprint();
```

### Long Format with Custom Salt
```javascript
const fingerprint = dPrintId.getInstance();
const deviceId = await fingerprint.generateFingerprint({
  format: 'long',
  salt: 'my-custom-salt'
});
```

### Minimal Components
```javascript
const fingerprint = dPrintId.getInstance();
const deviceId = await fingerprint.generateFingerprint({
  includeCanvas: false,
  includeAudio: false,
  includeWebGL: true
});
```

## API Integration Example

```typescript
import axios from 'axios';
import { dPrintId } from 'dprintjs';

const api = axios.create();

// Add fingerprint to all API requests
api.interceptors.request.use(async (config) => {
  const fingerprint = dPrintId.getInstance();
  const deviceId = await fingerprint.generateFingerprint();
  
  config.headers['Device-ID'] = deviceId;
  return config;
});
```

## Features in Detail

### Short Format (8 characters)
- Fast generation
- URL-friendly
- Suitable for quick device checks
- Example: `"k7lm9n2p"`

### Long Format (64 characters)
- SHA-256 based
- Highly unique
- Suitable for security-critical applications
- Example: `"8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92"`

### Components Used
- User Agent
- Screen properties
- Timezone
- Language preferences
- Hardware concurrency
- Device memory
- Platform information
- Canvas rendering
- Audio fingerprinting
- WebGL capabilities
- Touch support
- Browser plugins
- Plus additional entropy sources

## Browser Support

- Chrome (Latest)
- Firefox (Latest)
- Safari (Latest)
- Edge (Latest)
- Opera (Latest)
- Mobile browsers (iOS/Android)

## License

MIT License - see LICENSE file for details

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Support

For support, issues, or feature requests, please file an issue in the GitHub repository.