@seontechnologies/seon-id-verification

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:

npm install @seontechnologies/seon-id-verification

🛠️ Migration Guide: v1.x.x → v2.0.0

To upgrade to v2.0.0, run:

npm install @seontechnologies/seon-id-verification@^2.0.0

1. Style Import No Longer Needed

v1.x.x:

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:

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):

SeonIdVerification.initialize({
  baseUrl: 'https://idv-eu.seon.io',
  SEONCustomerData: {
    licenseKey: 'YOUR_LICENSE_KEY',
    referenceId: 'YOUR_REFERENCE_ID',
    email: '[e-mail]'
  }
});

After (v2.0.0):

SeonIdVerification.start({
  baseUrl: 'https://idv-eu.seon.io',
  licenseKey: 'YOUR_LICENSE_KEY',
  referenceId: 'YOUR_REFERENCE_ID',
  customerData: {
    email: '[e-mail]'
  }
});

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:

SeonIdVerification.on('completed', (status) => {
  // status: 'success' | 'pending' | 'failed' | 'unknown'
});

⚡️ Quick Start

Basic Initialization

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):

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:

customerData: {
  email: '[e-mail]',
  phoneNumber: '[phone]',
  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:

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
  • 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:

{
  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

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: '[e-mail]',
    phoneNumber: '[phone]',
    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.