API¶
This section details the methods and events available for interacting with the SDK, providing comprehensive control over its functionalities.
Available methods¶
You can obtain an instance of the SDK through a query selector and then leverage the methods outlined below.
/** Get Instance from rendered tag in the DOM */
const VDDocument = document.querySelector('vd-document')
/** Call initializeSdk method */
VDDocument.initializeSdk()
An instance of the SDK class is also globally available via window.vdDocument.VDDocument. This allows you to access static values or perform operations before attaching the SDK to the DOM.
initializeSdk¶
This method initializes and configures the SDK. It must be called before using any other SDK functionality.
For a practical usage example, refer to the Initialize installation section.
Parameters¶
config (required) — string | object
Defines the properties required to configure the SDK:
- If provided as a
string, it must be the path to the configuration file. - If provided as an
object, it must be a valid configuration object that complies with the defined schema.
See the Configuration object example for reference.
Return Value¶
Promise<boolean> — Resolves to true if the SDK was successfully initialized.
Example¶
const config = "myAssetsPaths/config.json"
const result: Promise<boolean> = await VDDocument.initializeSdk(config);
getPackageVersion()¶
Retrieves the current version of the SDK.
Return Value¶
string — Returns a string representing the SDK version, in the format x.x.x.
Example¶
const sdkVersion = VDDocument.getPackageVersion();
events¶
A static property that exposes all public SDK event names. Useful for subscribing to and managing SDK-related events dynamically.
Return Value¶
string[] — Returns an array of strings, each representing a public SDK event.
How to use¶
const events = window.vdDocument.VDDocument.events;
console.log(events); // ['VD_mounted', 'VD_loaded', ...]
Dispatched events¶
The SDK dispatches a set of events to communicate that the corresponding actions have been taken. Each event is logged in the console by the SDK in this manner event_name detail, and dispatched as CustomEvent containing a detail as described below:
| Event Name | Event Detail | Event Trigger | Notes |
|---|---|---|---|
| VD_mounted | detail: {"sdkName": "VD-DOCUMENT", "type": "info", "legacyEvent": "VDDocument_mounted", "legacyDetailIsUndefined": true} |
When the SDK is mounted | |
| VD_loaded | detail: {"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"} |
When the SDK is fully loaded | |
| VD_instructions | detail: {"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document",documentStep: "OBVERSE" or "REVERSE"} |
When the instructions of each document side are displayed | |
| VD_cameraPermissionsGranted | detail: {"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document",documentStep: "OBVERSE" or "REVERSE"} |
When the user grants camera permissions | |
| VD_cameraStarted | detail: {"sdkName": "VD-DOCUMENT", "type": "info", "cameraLabels": "camera label", "legacyEvent": "VDDocument_cameraStarted", "legacyDetailIsUndefined": true, "flowType": "document",documentStep: "OBVERSE" or "REVERSE"} |
When the camera starts successfully | |
| VD_cameraVideoPlayStarted | detail: {"type": "info", "sdkName": "VD-DOCUMENT", "size": {"width": 1920, "height": 1080}, "cameraLabels": "camera label", "legacyDetailIsUndefined": true, "legacyEvent": null, "flowType": "document",documentStep: "OBVERSE" or "REVERSE"} |
When the camera video playback begins | |
| VD_cameraFailureDefaultError | detail: {"type": "error", "errorType": "The camera of the device has not started.", "sdkName": "VD-DOCUMENT", "legacyEvent": "VDDocument_cameraFailureError", "legacyDetailIsUndefined": true, "flowType": "document",documentStep: "OBVERSE" or "REVERSE"} |
When camera can't be initialised for any reason | |
| VD_cameraFailurePermissionError | detail: {"errorType": "The browser does not accept the permissions of the camera", "flowType": "document", "legacyDetailIsUndefined": true, "legacyEvent": undefined, "sdkName": "VD-DOCUMENT", "type": "error",documentStep: "OBVERSE" or "REVERSE"} |
When camera permissions are denied | |
| VD_cameraFailureVideoNotFoundError | detail: {"errorType": "The video has not started on the device.", "flowType": "document", "legacyDetailIsUndefined": true, "legacyEvent": undefined, "sdkName": "VD-DOCUMENT", "type": "error",documentStep: "OBVERSE" or "REVERSE"} |
When no usable camera is found to perform the flow | |
| VD_successTickFinish | detail: {"type": "info", "sdkName": "VD-DOCUMENT", "legacyDetailIsUndefined": true, "flowType": "document",documentStep: "OBVERSE" or "REVERSE"} |
When the success tick animation finishes | |
| VD_reviewImage | detail: {"stage": "OBVERSE_REVIEW" or "REVERSE_REVIEW", "sdkName": "VD-DOCUMENT", "type": "info", "legacyEvent": "VDDocument_reviewImage", "legacyDetailIsUndefined": true, "flowType": "document",documentStep: "OBVERSE" or "REVERSE"} |
When the review screen is shown | |
| VD_continueClicked | detail: {"type": "info", "sdkName": "VD-DOCUMENT", "legacyEvent": "VDDocument_continueClicked", "legacyDetailIsUndefined": true, "flowType": "document",documentStep: "OBVERSE" or "REVERSE"} |
When the continue button is clicked in review | |
| VD_capture (obverse) | detail: {"flow": "document", "type": "info", "sdkName": "VD-DOCUMENT", "data": {"shouldUnmount": false, "manualCapture": false, "obverse": "image", "documentType": "ID1", "documentSide": "OBVERSE", "documentId": "XX",isLastCapture: false}, "legacyDetailIsUndefined": false, "legacyEvent": "VDDocument_obverseDetection", "legacyDetail": "image", "stage": "obverseDetection", "flowType": "document",documentStep: "OBVERSE" or "REVERSE"} |
When the front side of the document is captured | |
| VD_capture (reverse) | detail: {"flow": "document", "type": "info", "sdkName": "VD-DOCUMENT", "data": {"shouldUnmount": false, "manualCapture": false, "reverse": "image", "documentType": "ID1", "documentSide": "REVERSE", "documentId": "XX",isLastCapture: true}, "legacyDetailIsUndefined": false, "legacyEvent": "VDDocument_reverseDetection", "legacyDetail": "image", "stage": "reverseDetection", "flowType": "document",documentStep: "OBVERSE" or "REVERSE"} |
When the back side of the document is captured | |
| VD_manualCaptureButton | detail: {"type": "info","sdkName": "VD-DOCUMENT", "flowType": "document",documentStep: "OBVERSE" or "REVERSE"} |
When the user captures the document manually | |
| VD_processFinished | detail: {"sdkName": "VD-DOCUMENT", "type": "info", "legacyDetailIsUndefined": true, "flowType": "document"} |
When the process ends, either by completion or timeout | |
| VD_closeButtonClicked | detail: {"flowType": "document", "legacyDetailIsUndefined": true, "legacyEvent": undefined, "sdkName": "VD-DOCUMENT", "type": "info",documentStep: "OBVERSE" or "REVERSE"} |
hen the close button is clicked and user exits from confirmation modal | |
| VD_repeatClicked | detail: {"sdkName": "VD-DOCUMENT", "type": "info", "legacyEvent": "VDDocument_repeatClicked", "legacyDetailIsUndefined": true, "flowType": "document",documentStep: "OBVERSE" or "REVERSE"} |
When the repeat button is clicked in the review screen | |
| VD_maxRetriesExceeded | detail: {"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document",documentStep: "OBVERSE" or "REVERSE"} |
When the user reaches the maximum number of allowed capture retries | |
| VD_detectionTimeout | detail: {"flowType": "document", "legacyDetailIsUndefined": true, "legacyEvent": "VDDocument_detectionTimeout", "sdkName": "VD-DOCUMENT", "type": "info",documentStep: "OBVERSE" or "REVERSE"} |
When the process times out | To be removed in 2026.6 |
| VD_detectionTimeout | detail: {"flowType": "document", "legacyDetailIsUndefined": true, "legacyEvent": "VDDocument_detectionTimeout", "sdkName": "VD-DOCUMENT", "type": "error",documentStep: "OBVERSE" or "REVERSE"} |
When the process times out | |
| VD_orientationStyleChanged | detail: {"data": {"sdkInPortrait": true}, "flowType": "document", "legacyDetail": null, "legacyDetailIsUndefined": true, "legacyEvent": null, "sdkName": "VD-DOCUMENT", "type": "info",documentStep: "OBVERSE" or "REVERSE"} |
When screen orientation is not allowed | |
| VD_orientationChanged | detail: {"data": {"orientation": "landscape"}, "flowType": "document", "legacyDetail": {"orientation": "landscape"}, "legacyDetailIsUndefined": false, "legacyEvent": "VDDocument_orientationChanged", "sdkName": "VD-DOCUMENT", "type": "info",documentStep: "OBVERSE" or "REVERSE"} |
When orientation changes to unsupported layout | |
| VD_restartClicked | detail: {"type": "info", "sdkName": "VD-DOCUMENT", "legacyDetailIsUndefined": true, "flowType": "document"} |
When the restart button is clicked after feedback | |
| VD_restartProcess | detail: {"sdkName": "VD-DOCUMENT", "type": "error", "code": 8002, "errorType": "SDK detection fails and should be restarted", "legacyEvent": "VDDocument_restartProcess", "legacyDetailIsUndefined": true, "flowType": "document"} |
When the process needs to be restarted due to an error | |
| VD_processRestarted | detail: {"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"} |
When the process is restarted | |
| VD_unmounted | detail: {"sdkName": "VD-DOCUMENT", "type": "info", "legacyEvent": "VDDocument_unmounted", "legacyDetailIsUndefined": true} |
When the SDK is unmounted | |
| VD_loseFocus | detail: {"sdkName": "VD-DOCUMENT", "type": "error", "flowType": "document"} |
When the window loses focus | To be removed in 2026.6 |
| VD_loseFocus | detail: {"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"} |
When the window loses focus |
VD_cameraFailurePermissionError in Safari¶
In safari these permission errors can happen indefinitely, please visit the FAQ page for more information.