@seontechnologies/seon-id-verification
Version:
An advanced SDK for natural person identification through document scanning, facial recognition, designed for secure and efficient user verification.
384 lines (297 loc) • 11.5 kB
Markdown
# SEON ID Verification SDK for Web
Our SDK offers a comprehensive suite of features designed to cater to a wide range of document validation and recognition needs. Below is a breakdown of the key features available:
## 💡 Features
**🤖 Document Validation and Content Verification**
- **Document Type Recognition:** Automatically identifies the type of document presented, whether it's an ID card, passport, driver's license, or any other official document.
- **Content Validation:** Extracts and validates the textual information from documents, ensuring the data's integrity and accuracy. This includes checking the validity of names, dates, document numbers, and other critical information.
- **Forgery Detection:** Utilizes advanced algorithms to detect and alert on any signs of tampering or forgery within the document, ensuring the authenticity of the presented documents.
- **Proof of Address Flow:** Verifies the provided proof of address documents, by extracting and validating the textual information to ensure the address's accuracy and authenticity.
**👨 Facial Recognition**
- **Identity Verification:** Compares the facial image on the document with the person presenting it to ensure they are the same individual, enhancing security and preventing identity fraud.
- **Liveness Detection:** Detects real-time presence and distinguishes between a live person and a spoofing attempt, such as using photographs or videos, to ensure that the verification process is secure.
<!-- **✌️ Hand Gesture Recognition**
- **Gesture Control:** Enables interaction with devices or applications through simple hand gestures, making the user interface more intuitive and accessible.
- **Complex Gesture Recognition:** Our SDK can recognize complex hand gestures, offering sophisticated controls for applications requiring nuanced interactions.
- **Real-time Processing:** Processes and recognizes hand gestures in real-time, ensuring a seamless and responsive user experience. -->
---
## 🚀 Installation
Install the SDK in your project:
```bash
npm install @seontechnologies/seon-id-verification
```
---
## 🛠️ Migration Guide: v1.x.x → v2.0.0
To upgrade to v2.0.0, run:
```bash
npm install @seontechnologies/seon-id-verification@^2.0.0
```
### 1. Style Import No Longer Needed
**v1.x.x:**
```js
import '@seontechnologies/seon-id-verification/styles';
```
**v2.0.0:**
This import is no longer required. All necessary styles are included automatically.
### 2. Initialization Changes
- **v1.x.x:**
You could use `SeonIdVerification.initialize(config)` and then call `SeonIdVerification.start()`.
- **v2.0.0:**
The `initialize` method is no longer required. You can pass the configuration directly to `start`:
```js
SeonIdVerification.start({
/* configuration options */
});
```
> **Note:**
>
> - `initialize` is still available for backward compatibility, but is not required if you pass the configuration directly to `start`.
> - `initialize` is no longer async, so you do not need to use `await` or `.then()` with it.
### 3. Configuration Object Changes
Key differences in v2.0.0:
- `licenseKey`, `referenceId`, `type`, and `templateId` are now top-level properties (not nested under `SEONCustomerData`).
- The `SEONCustomerData` object is now renamed to `customerData` and contains only user/customer-specific fields. (such as `email`, `phoneNumber`, `name`, etc.).
**Before (v1.x.x):**
```js
SeonIdVerification.initialize({
baseUrl: 'https://idv-eu.seon.io',
SEONCustomerData: {
licenseKey: 'YOUR_LICENSE_KEY',
referenceId: 'YOUR_REFERENCE_ID',
email: 'user@example.com'
}
});
```
**After (v2.0.0):**
```js
SeonIdVerification.start({
baseUrl: 'https://idv-eu.seon.io',
licenseKey: 'YOUR_LICENSE_KEY',
referenceId: 'YOUR_REFERENCE_ID',
customerData: {
email: 'user@example.com'
}
});
```
See the updated `FlowConfiguration` and `customerData` sections below for details.
### 4. Event Name Changes
- `start` → `started`
- `completedSuccess`, `completedPending`, `completedFailed` → now all trigger the `completed` event with an additional completion type/status argument.
- New events:
- `opened`: Flow UI opened
- `closed`: Flow UI closed
**Example:**
```js
SeonIdVerification.on('completed', (status) => {
// status: 'success' | 'pending' | 'failed' | 'unknown'
});
```
---
## ⚡️ Quick Start
### Basic Initialization
```js
import { SeonIdVerification } from '@seontechnologies/seon-id-verification';
SeonIdVerification.initialize({
baseUrl: 'https://idv-eu.seon.io', // or https://idv-us.seon.io
licenseKey: 'YOUR_LICENSE_KEY',
referenceId: 'YOUR_REFERENCE_ID',
language: 'en',
templateId: 'YOUR_TEMPLATE_ID',
customerData: {...},
// ...other configuration options
});
// Start the verification flow
SeonIdVerification.start();
```
You can also omit the `initialize` call and pass the configuration object directly to the `start` method.
### Rendering Modes
The SDK supports several rendering modes:
- **fullscreen**: Open the flow in fullscreen mode (default)
- **inline**: Embed the flow in a specific container (`containerId` required)
- **popup**: Open the flow in a popup window
**Example (inline):**
```js
SeonIdVerification.initialize({
...config,
renderingMode: 'inline',
containerId: 'idv-container',
});
```
---
## 🛠️ Configuration Reference
### `FlowConfiguration` Reference
The main configuration object (`FlowConfiguration`) supports:
- `baseUrl` (required): API base URL
- `licenseKey` (required): Your SEON IDV license key
- `referenceId` (required): Unique reference for the verification flow
- `language`: UI language (e.g., 'en')
- `type`: Verification type (e.g., 'registration', 'login')
- `templateId`: Template identifier
- `customerData`: Additional customer/user info
- `theme`: Theme configuration
- `alwaysTransferFromDesktop`: Force desktop to mobile transfering
- `renderingMode`: 'inline' | 'fullscreen' | 'popup' (default: 'fullscreen')
- `containerId`: DOM element ID to mount the flow (required if `renderingMode` is 'inline')
See TypeScript types in `src/types/FlowConfiguration.ts` for advanced options.
### `customerData` Reference
The `customerData` object allows you to pass additional user/customer information to the verification flow. This can improve the verification experience and is often required for compliance.
- `email`: User's email address
- `phoneNumber`: User's phone number
- `name`: User's full name
- `userId`: Internal user identifier
- `countryISOCode`: ISO country code, e.g., 'US'
- `address`: User's address
- `dateOfBirth`: Object with user's date of birth
- `day`: Day of birth (number)
- `month`: Month of birth (number)
- `year`: Year of birth (number)
- `postalCode`: Postal code
- `additionalProperties`: Object with extra key-value pairs
**Example:**
```js
customerData: {
email: 'user@example.com',
phoneNumber: '+1234567890',
name: 'John Doe',
userId: 'user-123',
countryISOCode: 'US',
address: '123 Main St, New York, NY',
dateOfBirth: {
day: 1,
month: 1,
year: 1990
},
postalCode: '10001',
additionalProperties: {
loyaltyId: 'abc-123',
customField: 'value'
}
}
```
---
## 📣 Events
You can listen for key events during the verification flow:
- `opened`: Flow UI opened
- `closed`: Flow UI closed
- `started`: Verification started
- `completed`: Verification completed (with status)
- `cancelled`: Flow cancelled by user
- `error`: Error occurred (with error code)
**Example:**
```js
SeonIdVerification.on('completed', (status) => {
// Handle completion (status: 'success' | 'pending' | 'failed' | 'unknown')
});
SeonIdVerification.on('error', (errorCode) => {
// Handle error
});
```
## 🖍️ Styling
You can customize the appearance of the verification UI using the `theme` property in your `FlowConfiguration` object.
### `theme` Reference
The `theme` object supports the following fields:
- `light`: Light mode theme overrides
- `baseTextOnLight`: Text color on light backgrounds
- `baseTextOnDark`: Text color on dark backgrounds
- `baseAccent`: Accent color
- `baseOnAccent`: Text color on accent backgrounds
- `dark`: Dark mode theme overrides
- `baseTextOnLight`: Text color on light backgrounds
- `baseTextOnDark`: Text color on dark backgrounds
- `baseAccent`: Accent color
- `baseOnAccent`: Text color on accent backgrounds
- `fontFamily`: Font family for the UI
- `fontUrl`: URL for the custom font
- `fontWeight`: Font weights to use
**Notes:**
- All color values should be valid CSS color strings (hex, rgb, hsl, etc.).
- The theme is applied within the iframe, so parent app CSS does not affect the verification UI.
- All properties are optional.
- For advanced branding, contact SEON support.
**Example:**
```js
{
theme: {
light: {
baseTextOnLight: '#3e5a93',
baseTextOnDark: 'rgb(255, 255, 255)',
baseAccent: '#467024',
baseOnAccent: 'rgb(255, 255, 255)',
},
dark: {
baseTextOnLight: '#dbfff1',
baseTextOnDark: 'rgb(255, 255, 255)',
baseAccent: 'hsl(52 86% 46% / 1)',
baseOnAccent: '#11361c',
},
fontFamily: 'cursive',
fontUrl: "url('https://.../font.ttf')",
fontWeight: '400 500 600 700 800 900',
}
}
```
**Notes:**
- All color values should be valid CSS color strings (hex, rgb, hsl, etc.).
- The theme is applied within the iframe, so parent app CSS does not affect the verification UI.
- For advanced branding, you may request a custom template or contact SEON support.
---
## 💻 Usage Example
```javascript
import { SeonIdVerification } from '@seontechnologies/seon-id-verification';
SeonIdVerification.on('opened', () => {
console.log('SDK opened');
});
SeonIdVerification.on('closed', () => {
console.log('SDK closed');
});
SeonIdVerification.on('started', () => {
console.log('Flow started');
});
SeonIdVerification.on('error', (err) => {
console.log('Error code: ', err);
});
SeonIdVerification.on('completed', (type) => {
console.log('Flow completed with type: ', type);
});
SeonIdVerification.initialize({
baseUrl: 'YOUR_BASE_URL',
customerData: {
licenseKey: 'YOUR_LICENSE_KEY',
referenceId: 'YOUR_REFERENCE_ID',
type: 'id-verification',
email: 'test-elek@seon.io',
phoneNumber: '+36301234567',
name: 'Test Elek',
userId: 'test-elek',
countryISOCode: 'us',
address: '132, My Street, New York 12',
templateId: 'YOUR_TEMPLATE_ID',
dateOfBirth: {
day: 1,
month: 1,
year: 2000,
},
postalCode: '12345',
additionalProperties: {
additionalProp1: 'value1',
additionalProp2: 'value2',
additionalProp3: 'value3',
},
},
language: 'en',
});
SeonIdVerification.start();
```
## 🕸️ Browser Compatibility
| Browser | Version |
| ------------------- | ------- |
| Chrome | 96 |
| Safari | 15 |
| Firefox | 79 |
| Opera | 82 |
| iOS Safari | 15 |
| Android Browser | 81 |
| Chrome for android | 96 |
| Firefox for android | 79 |
## 📝 License Terms
The detailed license terms can be viewed at the following link: ®️[SEON License Terms](https://seon.io/resources/legal-and-security/legal/#terms-of-service).