dikript-react-identity-comparison-sdk/README.md

A Dikript's React SDK for identity comparison and liveness checks.

# Dikript React Identity Comparison SDK

## Overview

Dikript React Identity Comparison SDK is a powerful React component library for integrating identity comparison and liveness checks into your web applications. This SDK provides an easy-to-use interface for capturing user photos, performing liveness checks, and integrating with Dikript's biometric API.

## Features

- Live camera feed for face detection
- Real-time face landmark detection
- Liveness check functionality
- Identity comparison functionality
- Customizable UI components
- Full TypeScript support
- Easy integration with React applications
- Request timeout handling to prevent hanging processes
- Visual feedback during processing states

## CSS Class Names

All CSS class names in this SDK are prefixed with `dikript` to avoid naming conflicts with your application's CSS. For example:

- `dikriptLivenessPopup` - The main container for the popup
- `dikriptPopupContent` - The content container
- `dikriptHeader` - The header section
- `dikriptActionButton` - Action buttons
- `dikriptCameraContainer` - The camera container

This ensures that the SDK's styles won't interfere with your application's styles.

## Installation

```bash
npm install dikript-react-identity-comparison-sdk
# or
yarn add dikript-react-identity-comparison-sdk
```

## Usage

### React + JavaScript

```jsx
import React, { useState } from 'react';
import { IdentityComparisonPopup } from 'dikript-react-identity-comparison-sdk';

function App() {
  const [showPopup, setShowPopup] = useState(false);
  
  const handleIdentityResult = (result) => {
    console.log('Identity comparison result:', result);
    // Handle the identity comparison result
  };
  
  return (
    <div>
      <button onClick={() => setShowPopup(true)}>
        Start Identity Verification
      </button>
      
      {showPopup && (
        <IdentityComparisonPopup
          apiKey="your_api_key_here"
          name="Your App Name"
          apiUrl="https://api.dikript.com/dikript/api/v1/biometrics"
          onClose={() => setShowPopup(false)}
          onIdentityComparisonResult={handleIdentityResult}
          modelPath="/models"
        />
      )}
    </div>
  );
}

export default App;
```

### React + TypeScript

```tsx
import React, { useState } from 'react';
import { 
  IdentityComparisonPopup, 
  IdentityComparisonResponse,
  IdType
} from 'dikript-react-identity-comparison-sdk';

const App: React.FC = () => {
  const [showPopup, setShowPopup] = useState(false);
  
  // Custom ID types
  const customIdTypes: IdType[] = [
    { value: 'NIN', label: 'National ID Number' },
    { value: 'PASSPORT', label: 'International Passport' },
    { value: 'DRIVERSLICENSE', label: 'Driver\'s License' }
  ];
  
  const handleIdentityResult = (result: IdentityComparisonResponse): void => {
    console.log('Identity comparison result:', result);
    // Handle the identity comparison result
  };
  
  return (
    <div>
      <button onClick={() => setShowPopup(true)}>
        Start Identity Verification
      </button>
      
      {showPopup && (
        <IdentityComparisonPopup
          apiKey="your_api_key_here"
          name="Your App Name"
          apiUrl="https://api.dikript.com/dikript/api/v1/biometrics"
          onClose={() => setShowPopup(false)}
          onIdentityComparisonResult={handleIdentityResult}
          modelPath="/models"
          idTypes={customIdTypes}
        />
      )}
    </div>
  );
};

export default App;
```

## Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| apiKey | string | Yes | Your Dikript API key |
| name | string | Yes | The name of your application |
| apiUrl | string | Yes | The URL for the identity comparison API endpoint |
| onClose | () => void | Yes | Callback function called when the popup is closed |
| onIdentityComparisonResult | (result: IdentityComparisonResponse) => void | Yes | Callback function called with the result of the identity comparison |
| modelPath | string | No | Path to the face-api.js models directory. Defaults to '/models' if not provided |
| idTypes | IdType[] | No | Array of ID types to display in the dropdown. Defaults to BVN, Phone Number, FRSC, and NIN if not provided |
| apiTimeout | number | No | Timeout in milliseconds for API requests. Defaults to 30000 (30 seconds) |

## Response Types

```typescript
interface LivenessResponse {
  isLive: boolean;
  confidence: number;
  message?: string;
}

interface IdentityComparisonResponse {
  isMatch: boolean;
  confidence: number;
  message?: string;
  matchDetails?: {
    faceMatch?: boolean;
    idMatch?: boolean;
  };
}

interface IdType {
  value: string;  // Value to be sent to the API
  label: string;  // Display label for the dropdown
}
```

## Customizing ID Types

You can customize the ID types that are displayed in the dropdown by providing an array of `IdType` objects to the `idTypes` prop:

```jsx
import React, { useState } from 'react';
import { IdentityComparisonPopup } from 'dikript-react-identity-comparison-sdk';

function App() {
  const [showPopup, setShowPopup] = useState(false);
  
  // Custom ID types
  const customIdTypes = [
    { value: 'NIN', label: 'National ID Number' },
    { value: 'PASSPORT', label: 'International Passport' },
    { value: 'DRIVERSLICENSE', label: 'Driver\'s License' }
  ];
  
  return (
    <div>
      <button onClick={() => setShowPopup(true)}>
        Start Identity Verification
      </button>
      
      {showPopup && (
        <IdentityComparisonPopup
          apiKey="your_api_key_here"
          name="Your App Name"
          apiUrl="https://api.dikript.com/dikript/api/v1/biometrics"
          onClose={() => setShowPopup(false)}
          onIdentityComparisonResult={(result) => console.log(result)}
          idTypes={customIdTypes}
        />
      )}
    </div>
  );
}

export default App;
```

## Integration with Face-API.js Models

This SDK uses Face-API.js for face detection and landmark recognition. You need to make the Face-API.js models available in your application.

### Option 1: Default Location (Public Folder)

By default, the SDK looks for models in the `/models` path of your application. Place the models in your application's public folder:

```
public/
  models/
    tiny_face_detector_model-weights_manifest.json
    tiny_face_detector_model-shard1
    face_landmark_68_model-weights_manifest.json
    face_landmark_68_model-shard1
```

### Option 2: Custom Location

If you want to store the models in a different location, you can specify the path using the `modelPath` prop:

```jsx
<IdentityComparisonPopup
  // other props...
  modelPath="/assets/face-api-models"
/>
```

With this configuration, the SDK will look for models at:

```
public/
  assets/
    face-api-models/
      tiny_face_detector_model-weights_manifest.json
      tiny_face_detector_model-shard1
      face_landmark_68_model-weights_manifest.json
      face_landmark_68_model-shard1
```

### Downloading the Models

Download the models from [face-api.js models](https://github.com/justadudewhohacks/face-api.js/tree/master/weights)

Required models:
- tiny_face_detector_model
- face_landmark_68_model

## Testing Locally

Follow these steps to test the SDK locally:

1. Clone the repository:
   ```sh
   git clone https://github.com/dikript/react-identity-comparison-sdk.git
   cd react-identity-comparison-sdk
   ```

2. Install dependencies:
   ```sh
   npm install
   ```

3. Build the SDK:
   ```sh
   npm run build
   ```

4. Download the Face-API.js models as mentioned above and place them in a `public/models` directory.

5. Serve the example:
   ```sh
   npx serve .
   ```

6. Open your browser and navigate to the example:
   ```
   http://localhost:3000/examples/
   ```

## Development

To set up the project for development:

1. Clone the repository
2. Install dependencies:
   ```bash
   npm install
   ```
3. Start the development server:
   ```bash
   npm run dev
   ```

## Building

To build the SDK:

```bash
npm run build
```

## Testing

Run tests with:

```sh
npm test
```

## License

This project is licensed under the MIT License.

## Support

For any questions or support, please contact Dikript Solutions at tech@dikript.com.

## Recent Updates

### Version 1.1.3
- Fixed issue where "Capture Photo" button remains visible during identity comparison processing
- Added loading overlay to clearly show when identity verification is in progress
- Implemented timeout handling for API requests to prevent hanging requests
- Improved error handling for identity comparison process

### Version 1.1.2
- Added support for customizable ID types through the new `idTypes` parameter
- Added `IdType` interface to represent ID type options
- Updated documentation and examples to demonstrate the new feature