Home
IMPORTANT NOTE
This is not the latest version of our SDKs. 3.X versions are going to be deprecated and our recommendation is to update to a 4.X version. Bear in mind that 4.X versions represent a big change from the previous major version, providing more capabilities and potential. At the same time, It means a break in backward compatibility that must be managed using the provided migration guide. Please make sure to perform proper tests in development environments to ensure that everything is working as expected.
Description¶
VDDocument captures document images, guiding the user in a self-contained and accessible system. VDDocument retrieves the following information:
- Document obverse (front side) image of all supported documents.
- Document reverse (back side) image for supported two-sided documents.
VDDocument takes into account the type of device being used and attempts to launch the camera (front facing or rear) that will provide the user with the best experience:
- Rear camera is used on mobile devices (smartphones, tablets…)
- Front camera is used on computers (desktops, laptops…)
The following permission is required for the framework to work:
- Camera.
To improve user experience, VDDocument attempts to capture images of the document automatically, by having the user center each side in a frame. VDDocument uses several algorithms to detect a document in the camera’s field of vision, and snaps the photo without need for further user action. Also, the user can take a photo manually by touching/clicking on the framed document.
The camera attempts to start at Full HD (1080p), but lower resolutions are intended whether the devices are unable to support the optimal one.
The photo is taken in .JPG format, being a 1080p capture about 500KB on size.
Specifications¶
Desktop Browsers¶
| Browser Name | Minimum version | Current version |
|---|---|---|
| Chrome | 57 | 121 |
| Firefox | 52 | 122 |
| Safari | 11.2 | 17.3 |
| Opera | 44 | 106 |
| Edge | 16 | 121 |
Mobile and Tablets Browsers¶
| Browser Name | Platform | Minimum version | Current version |
|---|---|---|---|
| Chrome | Android | 57 | 120 |
| Firefox | Android | 52 | 119 |
| Edge | Android | 42 | 121 |
| Opera Mobile | Android | 46 | 73 |
| Samsung Internet | Android | 7.2 | 23 |
| Safari | iOS | 11.2 | 17.3 |
Current version at 2024/01/12 GetUserMedia WebAssembly
The size of the SDK is 4.3MB
Additionally, some dependencies will be needed. These are:
- cv.js: 5.1 MB
Integration¶
VDDocument is built as a stand-alone module with a single external dependency:
- VDDocument.js file contains the core functionality.
- cv.js file contains the external dependency.
Place VDDocument.js and cv.js with the other static assets of your website.
Example of structure:
- public
- opencv/cv.js
- index.html
- VDDocument.js
In your HTML, for a correct operation with Safari on iPhone it is necessary that the HTML begins with the <!DOCTYPE html> tag. Moreover, right before the closing tag of the body element, place two script tags:
<script type="application/javascript" src="path_to_static_assets/VDDocument.js" charset="UTF-8"></script>
<script type="application/javascript" src="path_to_static_assets/cv.js" onerror="CVLoadError()"></script>
At the location in your HTML where VDDocument should mount, place a div element with a unique id or class name. The id “target” is used here as an example:
<div id='target'></div>
The target must have defined width and height sizes values; here is an example taking relative values from the parent node:
#target {
width: 100%,
height: 100%,
}
The following code shows how to mount the SDK with the recommended configuration:
function sdkStart() {
const VDDocument = makeVDDocumentWidget();
VDDocument({
targetSelector: '#target',
documents: ['ES2'],
detectionMessageBackgroundColor: '#000D44',
detectionMessageTextColor: '#FFFFFF',
confirmationDialogBackgroundColor: '#ffffff',
confirmationColorTick: '#078B3C',
confirmationDialogTextColor: '#000D44',
confirmationDialogButtonTextColor: '#FFFFFF',
confirmationCaptureButtonBackgroundColor: '#000D44',
confirmationRepeatButtonTextColor: '#000D44',
confirmationRepeatButtonBackgroundColor: 'transparent',
outerGlowCenteringAidDefault: '#000D44',
outerGlowCenteringAidDetecting: '#000D44',
infoUserDocumentBackgroundColorTop: '#000D44',
infoUserDocumentBackgroundColor: '#ffffff',
infoUserDocumentTextColor: '#000D44',
infoUserDocumentBackgroundColorButton: '#000D44',
infoUserDocumentTextColorButton: '#ffffff',
infoUserDocumentBorderColor: '#000D44',
sdkBackgroundColorInactive: '#ffffff',
errorActionButtonTextColor: '#000D44',
errorDisplayTextColor: '#000D44',
errorDisplayBackgroundColor: '#ffffff',
errorDisplayIconColor: '#000D44',
borderColorCenteringAidDetecting: '#078B3C',
});
}
Before sdkStart function, it is needed a pre-load of the models that uses cv.wasm for detecting documents. The next picture shows this calling process:
try {
var Module = {
onRuntimeInitialized: function () {
if (window.cv instanceof Promise) {
window.cv.then(target => {
window.cv = target;
sdkStart();
});
} else {
// for backward compatible
sdkStart();
}
},
};
} catch (e) {
console.error(e);
}
Example
<body>
<!-- installation of sdk starts -->
<div id="target"></div>
<script>
function sdkStart() {
const VDDocument = makeVDDocumentWidget();
VDDocument({
targetSelector: '#target',
documents: [
'ES2',
],
sdkBackgroundColorInactive: '#FFFFFF',
outerGlowCenteringAidDefault: '#000D44',
outerGlowCenteringAidDetecting: '#000D44',
detectionMessageBackgroundColor: '#000D44',
confirmationDialogTextColor: '#000D44',
confirmationDialogBackgroundColor: '#FFFFFF',
confirmationDialogButtonBackgroundColor: '#FFFFFF',
confirmationColorTick: '#078B3C',
confirmationCaptureButtonTextColor: '#FFFFFF',
confirmationCaptureButtonBackgroundColor: '#000D44',
confirmationRepeatButtonTextColor: '#000D44',
confirmationRepeatButtonBackgroundColor: '#FFFFFF',
confirmationDialogLinkTextColor: '#000D44',
borderColorCenteringAidDetecting: '#078B3C',
infoUserDocumentBackgroundColor: '#FFFFFF',
infoUserDocumentTextColor: '#000D44',
infoUserDocumentBackgroundColorButton: '#000D44',
infoUserDocumentTextColorButton: '#FFFFFF',
infoUserDocumentBackgroundColorTop: '#000D44',
infoUserDocumentBorderColor: '#000D44',
loadingSpinnerColor: '#000D44',
loadingSpinnerScreenBackgroundColor: '#FFFFFF',
errorDisplayBackgroundColor: '#FFFFFF',
errorDisplayTextColor: '#000D44',
errorDisplayIconColor: '#000D44',
errorActionButtonBackgroundColor: '#FFFFFF',
errorActionButtonTextColor: '#000D44',
});
}
function CVLoadError() {
Module.printErr('Failed to load/initialize cv.js');
}
try {
var Module = {
onRuntimeInitialized: function () {
if (window.cv instanceof Promise) {
window.cv.then((target) => {
window.cv = target;
sdkStart();
})
} else {
sdkStart();
}
}
}
} catch (e) {
console.error(e)
}
</script>
<script type="application/javascript" src="../assets/sdk/VDDocument.js" charset="UTF-8"></script>
<script type="application/javascript" src="../assets/sdk/cv.js" onerror="CVLoadError()"></script>
<!-- installation of sdk ends -->
</body>
Integration in Angular¶
In file, angular.json:
"assets": [
"src/favicon.ico",
"src/assets",
],
"scripts": [
"src/assets/libs/VDDocument.js",
"src/assets/libs/cv_init.js",
"src/assets/libs/cv.js",
],
In folder, src/assets/libs add new file cv_init.js, with this code:
try {
var Module = {
onRuntimeInitialized: function () {
if (window.cv instanceof Promise) {
window.cv.then(target => {
window.cv = target;
sdkStart();
});
} else {
sdkStart();
}
},
};
} catch (e) {
console.error(e);
}
Use¶
The SDK gives one global method called getSDKversion, this method when called, it will return the version of the SDK.
Once VDDocument mounts, it can be unmounted programmatically by invoking the global function destroyVDDocumentWidget.
VDDocument unmounts itself after completing a successful detection of the document, or after detection times out. You can control how long it takes for the process to time out to a certain extent. Refer to the configuration section.
Other events are available from SDK that are listed on Type Definitions section.