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.

---

🚀 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
`

$3

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.

$3

- 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

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.

$3

- 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

$3

`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.

$3

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

$3

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.

$3

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.

$3

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
- logoUrl: URL for custom logo in light mode
- 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
- logoUrl: URL for custom logo in dark mode
- 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)',
logoUrl: 'https://example.com/light-logo.png',
},
dark: {
baseTextOnLight: '#dbfff1',
baseTextOnDark: 'rgb(255, 255, 255)',
baseAccent: 'hsl(52 86% 46% / 1)',
baseOnAccent: '#11361c',
logoUrl: 'https://example.com/dark-logo.png',
},
fontFamily: 'cursive',
fontUrl: 'https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap',
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

!react

`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.