Setup¶
There are two options to start a project:
- Using pre-built example projects that will fit into your solution framework.
- Following the instructions provided in section two.
1. List of projects examples by framework¶
Download the example that fits your needs:
2. Manual integration¶
We provide a demo application that shows how to integrate and run the SDK. In this section, it is explained how to run the demo as well as how to use it and what contains.
Steps to launch Demo¶
-
Download this zip file and then decompress it.
-
To run the demo, open a terminal in the extracted folder and run the following commands:
npm i -g serve serve . --ssl-key=certs/key.pem --ssl-cert=certs/cert.pem ┌───────────────────────────────────────────────────┐ │ │ │ Serving! │ │ │ │ - Local: https://localhost:3000 │ │ - On Your Network: https://192.168.9.192:3000 │ │ │ │ Copied local address to clipboard! │ │ │ └───────────────────────────────────────────────────┘
-
Go to
https://localhost:3000/demo
, or the value which appeared in the- Local
field above.
Files¶
In the demo
folder you will find the following files and folders:
- index.html The html to be launched.
- setup.js This is the integration code that allow to launch the sdk.
- config.json This is the file with all the sdk configuration.
- assets SDK bundle and dependencies required by the SDK.
- certs Self signed public key and private certificate to provide SSL on demo launch (visit next section Creating Self-Signed Certificate).
Note The files above are required for the demo to start properly. EDIT THEM CAREFULLY
Creating Self-Signed Certificate¶
To launch the demo without SSL warning you can create a self-signed certificate with the following command:
# openssl self-signed certificate
openssl req -x509 \
-sha256 -days 356 \
-nodes \
-newkey rsa:2048 \
-subj "/CN=docs.veridas.com/C=ES/L=Pamplona" \
-keyout rootCA.key -out rootCA.crt
Index.html¶
The index.html file loads the SDK package, while the setup.js script handles the loading and initiation of the SDK. It also creates a container where the SDK will be displayed.
This container must have a defined width and height for the sdk to be rendered correctly.
We recommend in mobile devices the size gets almost the full size of the viewport in order to avoid content overflows. This could be done using the following CSS rule "width: 100dvw, height:100dvh"
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<link rel="icon" type="image/x-icon" href="assets/images/veridasLogo.png" />
<title>SDK Video</title>
<script type="module" defer src="assets/vd-video.umd.js"></script>
<script src="setup.js"></script>
</head>
<body>
<div id="demoContainer" style="width:100dvw; height: 100dvh"></div>
</body>
</html>
Configuration input¶
When initializing the SDK, you can configure and customize the SDK. That way, you can provide a more personalized approach.
You can set its configuration, with the initializeSdk
function. This function supports two types of configuration:
- Config by File: You can set the configuration, passing the path to your configuration file (config.json), exposed on your server. For example:
VDVideo.initializeSdk("./config.json")
- Config by Object: You can also set the configuration, passing an config object to the
initializeSdk
function. For example:
const configObject = {
...
sdkVideo: {
flowType: { documents: "ES2_ID" },
},
...
}
VDVideo.initializeSdk(configObject)
This config object needs to follow the correct schema.
You can get more details about the configuration when starting the SDK, go to the Initialize SDK section of this method documentation.
Also, one of the important properties to set up is the pathAssets
. This is used to indicate the location to the assets folder and it is explained in the following section.
Property sdkVideo.pathAssets
¶
This important property is used by the SDK to load internal assets. You can check it's default value in our SDK Video Configuration table.
To add the pathAssets
property correctly, you can do it in two different ways:
- Absolute path: indicating the full path to the assets folder.
- Relative path: indicating the relative path from the location of the sdk to the folder.
If the assets folder is not a descendant of the sdk folder, you can use the ../
relative path to descend folders from the main sdk path or use an absolute path to indicate its location.
Property sdkVideo.flowType
¶
An important and recommended property you might consider configuring is flowType
. By default, it's set to { documents: "ES2_ID" }
. This property sets the type of flow the SDK will take from the list of document types and country codes that may be used with the documents configuration setting. Depending on your use case, you might find one flow more suited than the others.
The available options of documents for the flowType
can be checked in the Documents section of this documentation.
For example, if you would like to use the smart document detection flow, you can include the following in your configuration:
const optionalConfigObject = {
...
sdkVideo: {
flowType: { documents: "ES2_ID" },
},
...
}
Here is an example of a configuration file with optional configuration parameters:
{
"$schema": "./assets/schema.json",
"generic": {
"theme": {},
"common": {
"ui": {
"buttons": {
"close": {
"show": true
}
}
}
}
},
"sdkVideo": {
"flowType": {
"documents": "ES_IDCard_2015"
},
"views": {
"deviceRotated": {
"active": false
},
"capture": {
"successTick": {
"show": true
}
},
"instructions": {
"active": true
}
},
"pathAssets": "assets"
}
}
Here is an example configuration object with optional configuration parameters:
const optionalConfigObject = {
generic: {
common: {
ui: {
logo: { show: true, media: "veridasLogo.png" },
buttons: {
close: {
"show": false,
"media": "/images/closeButton.svg"
}
}
},
behavior: {
web: {
logEvents: true,
language: "browser"
}
}
}
},
sdkVideo: {
flowType: { documents: "ES2_ID" },
pathAssets: "assets"
},
}
This optional configuration object can be passed while initializing the SDK. If not provided, the SDK will use its default settings.
Moreover, it's not mandatory to provide all the configuration parameters suggested in the above example. You can selectively pass only certain configurations. For any parameters not explicitly specified, the SDK will seamlessly utilize the corresponding default settings.
Typography load¶
For the proper configuration of the default User Interface (UI) theme provided by Veridas, the SDK will automatically load two fonts, PublicSansNormal
and PublicSansRegular
if no other font is specified in the typographyBodyNormalFontFamily
and typographyBodyRegularFontFamily
fields of the theme section in the configuration object. Both fonts are included in the distribution and can be found in the assets/fonts folder.
If other fonts are specified in the configuration, those fonts must be loaded properly if they are not supported natively by the browser
. The following example shows the style rules for loading the PublicSansNormal font, both by file and by URL:
@font-face {
font-family: PublicSansNormal;
src: url(./assets/fonts/PublicSansNormal.ttf);
}
@font-face {
font-family: PublicSansNormal;
src: url(https://fonts.googleapis.com/css2?family=PublicSansNormal:ital,wght@1,500&display=swap);
}
NOTE: if the PublicSans fonts are not loaded, then the default font will be Arial so the UI will not resemble the Veridas default theme.
SDK Loader¶
The demo project will load the SDK after the window.onload event is dispatched, and the SDK tag vd-video is settled in the DOM. An example of this can be seen in the following code:
Note that this function instantiates the SDK in the DOM but does not start it.
let VDVideo, SdkEvents, isConfigByFile, demoContainer
window.onload = () => loadSDK()
function loadSDK() {
SdkEvents = window.vdVideo.VDVideo.events
demoContainer = document.querySelector('#demoContainer')
demoContainer.innerHTML = "<vd-video></vd-video>"
addListeners()
}
Events listener¶
The SDK triggers custom events so you can listen to them and execute certain logic. Check the api section for more information.
Let's see an example of three events very important for the operation of the SDK:
- VD_mounted: (Legacy VDVideo_mounted) Before you can use the public method initializeSdk to load the configuration and initialize the detecting and capturing process, the SDK must be fully loaded into memory. This event indicates that the SDK is now fully operational and waiting to be initialized. This is when you can call the initializeSdk method to start the SDK. See api section for more information on SDK methods.
- VD_restartProcess: (Legacy VDVideo_restartClicked) When for some reason, the detection process fails and needs to be repeated, the SDK emits this event to indicate that the detection process is going to be restarted.
- VD_capture: (Legacy VDVideo_faceDetection) Finally, when the detection process ends correctly, the SDK emits this event with the output data in its detail.
Here is the code for catching the SDK events and initialize the SDK. You should put this in your setup file:
/**
* @name eventHandlers
* @description Object with the event handlers for the SDK events
* @type {Object}
*/
const eventHandlers = {
VD_mounted: onSDKMounted, // Same as legacy event VDVideo_mounted
VD_restartProcess: handleRestartProcess, // Same as legacy event VDVideo_restartClicked
VD_capture: onSDKResult, // Same as legacy event VDVideo_faceDetection
VD_cameraVideoPlayStarted: onCameraVideoPlayStarted,
VD_processFinished: onProcessFinished,
VD_closeButtonClicked: onCloseButtonClicked,
VD_detectionTimeout: onDetectionTimeout
}
/**
* @name handleEvent
* @description Handles the SDK events for the events in the eventHandlers object
* @param {Object} e Event object
* @returns {void}
*/
function handleEvent(e) {
const handler = eventHandlers[e.type]
if (handler) {
handler(e)
}
}
/**
* @name addListeners
* @description Adds the event listeners for the SDK events in the `SdkEvents` array
*/
function addListeners() {
SdkEvents.forEach(sdkEvent => {
addEventListener(sdkEvent, e => {
handleEvent(e)
})
})
}
Initialize¶
Once the VD_mounted SDK event is dispatched, the function responsible for launching the SDK is invoked. This function can utilize an optional configuration, either defined within a file or an object.
This is illustrated in the example below.
async function launchSDK() {
VDVideo = document.querySelector("vd-video")
if (isConfigByFile) {
await VDVideo.initializeSdk('./config.json')
} else if (configObject) {
await VDVideo.initializeSdk(configObject)
} else {
await VDVideo.initializeSdk()
}
}
In the above example, the SDK can be initialized with a configuration (from a file or an object). If no configuration is provided, the SDK will utilize default settings.
Output Files¶
Finally, when the detection process ends correctly, the SDK emits VD_capture
event with the output data in its detail.
The output files are:
- video: mp4 video with recording of the full flow.
Basic setup.js
file¶
This is how we suggest your setup.js
file should look like at the end:
let VDVideo, SdkEvents, isConfigByFile, demoContainer
window.onload = () => loadSDK()
function loadSDK() {
SdkEvents = window.vdVideo.VDVideo.events
demoContainer = document.querySelector('#demoContainer')
demoContainer.innerHTML = "<vd-video></vd-video>"
addListeners()
}
/**
* @name eventHandlers
* @description Object with the event handlers for the SDK events
* @type {Object}
*/
const eventHandlers = {
VD_mounted: onSDKMounted, // Same as legacy event VDVideo_mounted
VD_restartProcess: handleRestartProcess, // Same as legacy event VDVideo_restartClicked
VD_capture: onSDKResult, // Same as legacy event VDVideo_faceDetection
VD_cameraVideoPlayStarted: onCameraVideoPlayStarted, // Example of custom function to handle the event
VD_processFinished: onProcessFinished, // Example of custom function to handle the event
VD_closeButtonClicked: onCloseButtonClicked, // Example of custom function to handle the event
VD_detectionTimeout: onDetectionTimeout // Example of custom function to handle the event
}
/**
* @name handleEvent
* @description Handles the SDK events for the events in the eventHandlers object
* @param {Object} e Event object
* @returns {void}
*/
function handleEvent(e) {
const handler = eventHandlers[e.type]
if (handler) {
handler(e)
}
}
/**
* @name addListeners
* @description Adds the event listeners for the SDK events in the `SdkEvents` array
*/
function addListeners() {
SdkEvents.forEach(sdkEvent => {
addEventListener(sdkEvent, e => {
handleEvent(e)
})
})
}
async function launchSDK() {
VDVideo = document.querySelector("vd-video")
if (isConfigByFile) {
await VDVideo.initializeSdk('./config.json')
} else if (configObject) {
await VDVideo.initializeSdk(configObject)
} else {
await VDVideo.initializeSdk()
}
}