Skip to content

Setup

There are two options to start a project:

  1. Using pre-built example projects that will fit into your solution framework.
  2. Following the instructions provided in section two.

1. List of projects examples by framework

Download the example that fits your needs

  1. Vue
  2. React
  3. Angular
  4. Lit Element

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

  1. Download this zip file and then decompress it.

  2. Copy your own SDK files to the root of the demo folder.

  3. 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!              │
     │                                                   │
     └───────────────────────────────────────────────────┘

  4. 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 Photo Document</title>
        <script type="module" defer src="assets/vd-document.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, by passing the path to your configuration file (config.json), exposed on your server. For example:
    await VDDocument.initializeSdk("./config.json")
  • Config by Object: You can also set the configuration, passing an config object to the initializeSdk function. For example:
const configObject = {
    ...
    sdkDocument: {
        flowType: {
            documents: "ES2_ID"
        },
    },
    ...
};
VDDocument.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 sdkDocument.pathAssets

This important property is used by the SDK to load internal assets. You can check it's default value in our SDK Document Configuration section.

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.

Here is an example of a configuration file with the minimum configuration parameters:

{
    "sdkDocument": {
        "views": {
            "instructions": {
                "active": true
            },
            "reviewImage": {
                "active": true
            },
            "capture": {
                "manualCapture": { "active": true, "manualCaptureButtonDelay": 1500 },
                "successTick": {
                    "show": true
                }
            },
            "deviceRotated": {
                "active": true,
                "onOrientation": "landscape"
            }
        }
    },
    "$schema": "./assets/schema.json",
    "generic": {
        "theme": {},
        "common": {
            "ui": {
                "buttons": {
                    "close": {
                        "show": true
                    }
                }
            }
        }
    }
}

Here is an example of the configuration object with the minimum configuration parameters:

const configObject = {
    generic: {
        theme: {
            colorAlertError: "#d63737",
            colorAlertSuccess: "#AEE4C1",
            colorAlertSuccessDark: "#53A335",
            colorNeutral00: "#ffffff",
            colorNeutral05: "#f2f2f2",
            colorNeutral20: "#cccccc",
            colorNeutral40: "#999999",
            colorNeutral80: "#333333",
            colorPrimaryDark: "#000D44",
            colorPrimaryMain: "#257CD0",
            colorPrimaryLight: "#528bb8",
            radiusSm: "8px",
            shadowSm: "0px 4px 8px rgba(0, 0, 0, 0.25)",
            typographyBodyNormalFontFamily: "PublicSansNormal",
            typographyBodyRegularFontFamily: "PublicSansRegular",
        },
        common: {
            ui: {
                logo: { show: true, media: "veridasLogo.png" },
                buttons: {
                    close: {
                        "show": false,
                        "media": "/images/closeButton.svg"
                    }
                }
            },
            behavior: {
                web: {
                    logEvents: true,
                    language: "browser"
                },
            },
        },
    },
    sdkDocument: {
        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-document 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 VDDocument, SdkEvents, isConfigByFile, demoContainer

window.onload = () => loadSDK()

function loadSDK() {
    SdkEvents = window.vdDocument.VDDocument.events
    demoContainer = document.querySelector('#demoContainer')
    demoContainer.innerHTML = "<vd-document></vd-document>"
    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 VDDocument_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_restartClicked: (Legacy VDDocument_restartProcess) 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 VDDocument_obverseDetection/VDDocument_reverseDetection) 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 VDDocument_mounted
    VD_restartClicked: handleRestartProcess, // Same as legacy event VDDocument_restartProcess
    VD_capture: onSDKResult, // Same as legacy event VDDocument_obverseDetection | VDDocument_reverseDetection
}

/**
 * @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)
        })
    })
}

SDK Launcher

After the VDDocument_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 following example:

async function launchSDK() {
    VDDocument = document.querySelector("vd-document")
    if (isConfigByFile) {
        await VDDocument.initializeSdk("./config.json")
    } else if (configObject) {
        await VDDocument.initializeSdk(configObject)
    } else {
        // This uses the configuration with the default values defined in the SDK Configuration
        await VDDocument.initializeSdk()
    }
}

Output Files

In case of launching a single document flow, the output files are:

  • obverse: base64 image with obverse captured data for all supported documents.
  • reverse: base64 image with reverse captured data for supported two-sided documents.

Basic setup.js file

This is how we suggest your setup.js file should look like at the end:

const pathAssets = "assets"
let VDDocument, SdkEvents, isConfigByFile, demoContainer

window.onload = () => loadSDK()

function loadSDK() {
    SdkEvents = window.vdDocument.VDDocument.events
    demoContainer = document.querySelector('#demoContainer')
    demoContainer.innerHTML = "<vd-document></vd-document>"
    addListeners()
}

/**
 * @name eventHandlers
 * @description Object with the event handlers for the SDK events
 * @type {Object}
 */
const eventHandlers = {
    VD_mounted: onSDKMounted, // Same as legacy event VDDocument_mounted
    VD_restartClicked: handleRestartProcess, // Same as legacy event VDDocument_restartProcess
    VD_capture: onSDKResult, // Same as legacy event VDDocument_obverseDetection | VDDocument_reverseDetection
}

/**
 * @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() {
    VDDocument = document.querySelector("vd-document")
    if (isConfigByFile) {
        await VDDocument.initializeSdk("./config.json")
    } else if (configObject) {
        await VDDocument.initializeSdk(configObject)
    } else {
        // This uses the configuration with the default values defined in the SDK Configuration
        await VDDocument.initializeSdk()
    }
}