npm:@idscan/idvc

README

Overview

Upon being switched on, the library integrates the component of capturing the documents and faces from a video to your page.

Use cases

Capture and determination of the document type
Capture of pdf417
Capture of MRZ
Capture of faces

Recommendations

Use a modern phone with a good camera having the definition of not less than 8 megapixels. The capture must be made in a well-lighted room. A document must be located at the uniform background.

Limitations

This component works in phones with the operating system Android in the browser Chrome (minimum version 52) and in phones with the operating system iOS (minimum version 11) in the browser Safari

Installation

$ npm install @idscan/idvc

This component contains JS, CSS files which require the mandatory import into your project.

Before importing it is necessary to set the webpack-configuration.

Note: The project must use the webpack 4 and later versions.

1.1. Add the following rules of loading to the field rules

{
    test: /\.css$/,
    use: ["style-loader", "css-loader"]
}

1.2. If you prefer to use neural networks from your domain, you should add the 'CopyWebpackPlugin' into the section 'plugins' which will copy the files, which are necessary for the work of the neural network, from the folder to another folder that should be selected by you.

Note: The structure inside the folder of the component 'networks' must be saved on the server with due regard to the nesting. There are binary files in the folder which do not have the extension. These files must be provided by the server with the header Content-Type: application/octet-stream.

new CopyWebpackPlugin ([
    {
    	from: 'node_modules/@idscan/idvc/dist/networks/**/*',
    	to: 'networks/[folder]/[name].[ext]',
    	toType: 'template'
    }
])

1.3. Import the library and css to your project.

import IDVC from '@idscan/idvc'
import  '@idscan/idvc/dist/css/idvc.css'

Initialization

Create an instance of the object 'IDVC'. The object takes one object of the component configuration as a parameter.

Available fields:

el (string) – id of an element on the page where the component will be integrated.

licenseKey (string) – key for the library

isShowManualSwitchButton (boolean | object) - enables/disables the button you are able to switch between the uploader and the video with. Boolean is both for mobile and desktop. Object {mobile: true, desktop: true} - set button showing for mobile or desktop. Default: true

showSubmitBtn (boolean) – enables/disables the "submit" button after capturing all the images. If a button is switched off, an event of sending the images will be created automatically after capturing all the images. Default: true

isShowVersion (boolean) - hide/show version of library in the bottom. Default: true

tapOnVideo (boolean) - tap and hold the video if you want to capture frame manual.. Default: false

tapBackSide (boolean) - tap and hold the screen to capture the back side of the ID. Default: false

minPDFframes (integer) - the option "minPDFframes" which determines the minimal number of frames for capturing the PDF417. Default: 1

parseMRZ (boolean) - if it is enabled, the captured mrz strings is converted into the parsed document fields. Thus on-server parsing won’t be necessary. At the Front and mrz steps, the parsedData object would be available. Default: false

tapFace (boolean) - tap and hold the screen to capture the face. Default: false

enableLimitation (boolean) - using Boolean parameter you are able to switch off the limitation for desktop browsers. Default: true

autoContinue (boolean) - this option switches on/off the automatic transition to the next step. Default: true

resizeUploadedImage (integer) - sets the maximum size for manually loaded pictures. Default: -1

showForceCapturingBtn (boolean) - Switches on the button over the video. On pressing this button, the capturing of the image will take place. Default: false

fixFrontOrientAfterUpload (boolean) - this option provides the possibility to adjust the correct position of the document in case of manual uploading. Default: false

enableFlash (boolean) - this option turns on/off the flash while capturing an image. Default: false

capturingMode - The option that switches the mode of capturing the front of the documents. Available values are 2,4, ‘none’. Type 2 - auto capturing with the help of determining the borders. Type 4 - auto capturing which analyses the text in the image. ‘None’ - switch off the auto capturing. This method should be used together with the option showForceCapturingBtn:true. Default: 4

steps (array) – array of steps which are necessary for you. Every step represents an object with the fields 'type' and 'name'. The field 'name' is the name of a step, which will be represented in the header. The field 'type' is a type of a step. Possible variants are:

front – capture of a document with the following analysis of the document type. In case if a document requires the back side, the step for the back side of a document will be added automatically. Use the step 'front' if you use the component for the document validation.
mrz – detection, capture and parsing of the mrz-code of a document
pdf – detection and capture of pdf417 of a document
face – detection and capture of a face using the front camera
capturing – capture of a document without analysis
barcode – detection, capture and parsing 1 dimensional (barcodes) or 2 dimensional (qr codes)

Steps can be combined in any order and in any combinations, except for the step 'front'.

E.g.:

steps:[
    {type: 'front', name: 'Image'},
    {type: 'face', name: 'Selfie'}
]

useCDN (boolean) - set to true if you prefer to load neural networks from cdn instead of your domain. Default: false

networkUrl (string) - path to the folder with neural networks. Specify the path on the server if you need to remove the folder to another location. The default path is 'networks'. Default: 'networks'

showPreviewForOneStep (boolean) - using this option you can hide the preview if you have only one step configured. Default: true

priority (string) - initial method of work of the component. Available values: 'uploader', 'camera', 'auto' (on desktop - uploader, on mobile - camera). Default: 'auto'

realFaceMode (string) - option that enable advanced capture with volumetric face detection. Available values: 'auto', 'all', 'none'. Auto - enable "realFaceMode" only for iphone. All - enable "realFaceMode" for all devices. None - disable this option. Default: 'auto'

types (array) – array of types of acceptable documents. If you are going to use the component for the document validation, you can limit the list of acceptable documents.

Available types (int):

ID (1) – USA driver license and USA ID (non-driver license), Canadian driver licenses,
Passport (2) – with 2 lines MRZ
PassportCard (3) – with 3 lines MRZ (most European IDs, USA passports/cards)
GreenCard (6) – USA Permanent Resident Cards (only MRZ),
InternationalId (7) – Internationally approved U.S. IDs with 3 lines MRZ

E.g.: types:

['ID', 'PassportCard']

Note: If you provide one type in the array, this type of document will not be analyzed further.

strictAllowedTypes (boolean) - strict allowed types mode makes a document not from the list of acceptable document types is throws an error. Default: false

enableGeolocation (boolean) - the option which allows getting user's latitude and longitude location. Default: false

displayParsedData (boolean) - the option which allows showing parsed results in modal window on submit. Default: false

onMounted - the function that will be called on the component mounted. This function doesn't return a value.

onChange - callback-function which will be called after change one step. The returnable value is the object with the type and the image

onCameraError - The function that is invoked in case if the camera is not available. The response value is the object with the error code and the message

onReset - callback-function which will be called after reset all the steps. The returnable value is the object with the steps

onRetakeHook - the function that will be called before reset the current step. The returnable value is the object with the current step

submit - callback-function which will be called after completing all the steps. The returnable value is the object with the following content:

{  "steps": [{
  	"img": "",
      	"type": "front"
    }…],
  "documentType": 1
}

where documentType – id of a document type ( ID – 1, Passport - 2, PassportCard – 3, GreenCard – 6, InternationalId – 7)

steps – steps with the type and the image in the format 'base64'.

Also, if you use automatic capture, in the "back" step trackstring will be returned (raw PDF417 data from Barcode encoded in base64)

Config example:

new IDVC ({
    networkUrl: 'networks',
    el: 'videoCapturingEl',
    licenseKey: '',
    types: ['ID', 'PassportCard'],
    showSubmitBtn: true,
    steps: [
        {type: 'front', name: 'Image'},
        {type: 'face', name: 'Selfie'}
    ]
})

Note: Request an license key for the library by emailing sales@idscan.net or support@idscan.net

Style Customization

To tweak the theme of the component you can redeclare variables in CSS custom properties. Don't forget to place the CSS file with redeclared variables below the component's CSS file. Redeclaration of CSS custom properties looks like this:

 .idvc {
   --btn-border-radius-big: 40px;
   --color-background-white: #000000;
 }

The component has the following customizable properties:

--btn-border-radius-big

default: 4px

radius of retake, continue, submit buttons

--btn-border-radius-small

default: 4px

radius of the manual switch button
radius of the messagebox

--color-text-secondary-light

default: #C4C4C4

'select document type' menus's checkmark

--color-positive-light

default: #17EA4C

success frame on capturing

--border-color-divider

default: #C0C0C0

message box's default border color
'select document type' menus's devider

--color-primary-light-2

default: #DCE7FD

primary button hover, focus colors

--color-primary-light-7

default: #85AAF7

transparent button hover and focus background color

--color-primary-light-9

default: #6291F4

transparent button border hover, focus colors
'select document type' menus's selected item background

--color-primary-dark-2

default: #080D18

primary button active colors
transparent button active font color and border color

--color-background-subheader

default: #F5F6F9

background of the bottom part of the active step in 'steps' section
'type not defined' select background of the modal window
scrollbar of 'result' modal window

--color-background-white

default: #FFF

uploader's background
background of 'result' modal window container
background of 'type not defined' modal window
background of 'document type-hint’ section

--border-color-base

default: #DCDFE6

border of 'type not defined' modal window select
border of 'document type-hint' section
borders of top part in 'steps' section
bottom icons of inactive step in 'steps' section
image background in 'steps' section

--color-primary

default: #5185F3

background of primary buttons
active step name, icon, and bottom line of the active step in 'steps' section
uploader labels, border
manual take picture button in video capturing
change the document type in 'document type-hint' section
step name on hover in 'steps' section
guideline inscription
background of the upload icon in the uploader
uploader's emphasized descriptions
disabled primary buttons
disabled button border
spinner's color

--color-success

default: #13CE66

succeeded steps in 'steps' section
face shape when capturing the video in face step
capture progress
valid sign of 'result' modal window container
hints on video capture
background of uploader's success sign

--color-danger

default: #FF4949

background and bottom border of the step error in 'steps' section
header of 'type not defined' modal window
invalid sign of 'result' modal window container
license error text

--color-warning

default: #FFC632

warning sign of uploader

--color-text-secondary

default: #909399

scrollbar of 'result' modal window
library version
descriptions of the uploader
close sign of 'result' modal window
name of the inactive step in 'steps' section

--color-black

default: #000

face shape icon in video capturing when the face is not detected at the face step
shadow of 'type not defined' modal window
caption of 'type not defined' modal window select
uploader's bold descriptions
shadow of 'result' modal window
bottom border of 'result' modal window row
options of change the document type in 'document type-hint' section
uploader's error sign stroke
uploader's error description

--color-white