API¶
Available methods¶
The next section outlines the methods that allow you to gain control over the SDK. As an example, you can obtain an instance of the SDK via a query selector, and then utilize the methods described in this section. Note you can use javascript or typescript if necessary.
/** Get Instance from rendered tag in the DOM */
const VDVideo = document.querySelector('vd-video')
/** Call initializeSdk method */
VDVideo.initializeSdk()
Note that an instance of the class is also available in window.vdVideo.VDVideo
, and you could use it before attaching it to the DOM, for example, to check the static values.
initializeSdk(config)¶
- This method initializes and configures the SDK. To see an example of use, see demo launcher setup section.
-
@Params
- sdkConfig: {string | object} It is a required parameter. Contains the properties for configuring the SDK. Its value can be the path to the configuration file (string) or the configuration object (object). In both cases they must follow the schema definition, see an example configuration object.
-
@Return
Promise<boolean>
The function returns a promise boolean which informs that the SDK was initialized successfully.
How to use¶
// config parameter can also be an object, with the same structure as the json schema, available in the assets folder (schema.json).
const config = "myAssetsPaths/config.json"
const result: Promise<boolean> = await VDVideo.initializeSdk(config);
events¶
- Static property that contains an array with all the SDK public events.
-
@Return
- {Array of Strings} The function return an array of strings.
How to use¶
const events = window.vdVideo.VDVideo.events;
getPackageVersion()¶
- This method is used to get the SDK version.
-
@Return
- {String} The function returns a string with the version of the SDK with the following format: x.x.x
How to use¶
const sdkVersion = VDVideo.getPackageVersion();
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 | Description | Event Payload |
---|---|---|
VD_cameraAbortError | Fired when there was an error trying to start the stream or when the camera devices fail to start the video. | detail:{type: string, errorType: string, sdkName: string, legacyEvent: string, legacyEventIsUndefined: boolean} |
VD_cameraFailureDefaultError | Fired if the camera on the device fails to launch. | detail:{type: string, errorType: string, sdkName: string, legacyEvent: string} |
VD_cameraFailureExternalInputError | Fired after detecting an attempting of image injection. | detail:{type: string, errorType: string, sdkName: string, legacyEvent: string} |
VD_cameraFailurePermissionError | Fired when the user does not accept the camera permissions in the browser. | detail:{type: string, errorType: string, sdkName: string, legacyEvent: string, legacyDetailIsUndefined: boolean} |
VD_cameraFailureVideoNotFoundError | Fired if the video on the device fails to launch. | detail:{type: string, errorType: string, sdkName: string, legacyEvent: string} |
VD_cameraRecorderSetupError | Fired after the camera encoder in the browser API has not been configured correctly. | detail:{type: string, errorType: string, sdkName: string, legacyEvent: string} |
VD_cameraRecorderSetup | Fired when the camera starts up and starts recording. | detail:{isAlternative: boolean, sdkName: string, legacyEvent: string, legacyDetailIsUndefined: boolean, mediaRecorderConfig: {audioBitsPerSecond: number, ignoredMutedMedia: boolean, mimeType: string, videoBitsPerSecond: number}, supportedPlayableMimetypes: array, supportedRecordingMimeTypes: array} |
VD_cameraRecorderStop | Fired after the camera recorder stops. | detail:{type: string, sdkName: string, legacyEvent: string, legacyDetailIsUndefined: boolean, alternativeBlob: string, isAlternative: boolean, _recordedBlob: object} |
VD_cameraStarted | Fired after the camera on the device is launched correctly. | detail:{sdkName: string, type: string, legacyEvent: string, legacyDetailIsUndefined: boolean, cameraLabels: string} |
VD_cameraVideoPlayStarted | Fired after the camera on the device is launched correctly. | detail:{type: string, sdkName: string, legacyEvent: string, legacyDetailIsUndefined: boolean, cameraLabels: string, size: { width: number, height: number}} |
VD_capture | Fired after successful detection. The detail property inside the event object contains a base64 jpg with the capture. The stage property that has the detail indicates in which part of the process the event has been launched. | detail:{flow: {documents: { areSmart: boolean, docRatio: number, documentType: string, documents: object, inputDocumentsConfig: string, requiredDocumentSides: array}}, type: string, sdkName: string, legacyEvent: string, legacyDetailIsUndefined: boolean, legacyDetail: string, data:{recording: {…}, xml: File, needsEncoding: false}} |
VD_closeButtonClicked | Fired after the close button is clicked. | detail:{type: string, sdkName: string, legacyEvent: string, legacyDetailIsUndefined: boolean} |
VD_dependenciesLoadingError | Fired after loading dependencies fail. | detail:undefined |
VD_loaded | Fired after loading dependencies and SDK is ready to capture. | detail:undefined |
VD_detectionTimeout | Fired after a configurable amount of time. | detail:{sdkName: string, type: string, legacyEvent: string, legacyDetailIsUndefined: boolean } |
VD_mounted | Fired after the SDK mounts correctly. | detail:{sdkName: string, type: string, legacyEvent: string, legacyDetailIsUndefined: boolean } |
VD_mountFailure | Fired if SDK fails to mount for any reason. | detail:{sdkName: string, type: string} |
VD_orientationChanged | Fired after the user changes the orientation of the device. This updates the UX/UI of the SDK with the new styles. | detail:{type: string, sdkName: string, legacyEvent: string, data:{orientation: string}, legacyDetailIsUndefined: boolean, legacyDetail: {orientation: string}} |
VD_processFinished | Fired when capture process is finished. | detail:{type: string, sdkName: string, legacyEventIsUndefined: boolean} |
VD_processRestarted | Fired when the restart button is clicked and the process is restarted. | detail:{type: string, sdkName: string} |
VD_restartClicked | Fired after the user clicks the restart button. | detail:{type: string, sdkName: string, legacyEvent: string, legacyDetailIsUndefined: boolean} |
VD_restartProcess | Fired after an error in the detection process and SDK require to be restarted. Error Codes: 8002 (DeviceRotated). | detail:{sdkName: string, type: string, errorType: string, code: number, legacyEvent: string, legacyDetailIsUndefined: boolean} |
VD_successTickFinish | Fired after success tick finish. | detail:{type: string, sdkName: string, legacyEvent: string, legacyDetailIsUndefined: boolean} |
VD_unmounted | Fired after the SDK unmounts. This requires removing the SDK from the DOM, when the SDK is completely disconnected it will notify you with this event. | detail:{type: string, sdkName: string, legacyEvent: string, legacyDetailIsUndefined: boolean} |
VD_orientationStyleChanged | Fired after orientation style changes. | detail:{data: {sdkInPortrait: false}, legacyDetail: {sdkInPortrait: boolean}, legacyDetailIsUndefined: boolean, legacyEvent: string, sdkName: string, type: string} |
If the logEvents(generic.common.behavior.web.logEvents) configuration is activated, each event and its detail is observed in the console:
VD_mounted {sdkName: 'VD-VIDEO', type: 'info', legacyDetailIsUndefined: true, legacyEvent:'VDVideo_mounted' }
VD_unmounted {sdkName: 'VD-VIDEO', type: 'info', legacyDetailIsUndefined: true, legacyEvent:'VDVideo_unmounted'}
VD_cameraVideoPlayStarted {sdkName: 'VD-VIDEO', type: 'info', cameraLabels: 'FaceTime HD Camera (3A71:F4B5)', legacyDetailIsUndefined: true, legacyEvent:'VDVideo_cameraVideoPlayStarted', size: { width: 1920, height: 1080 }}
VD_continueClicked { type: 'info', sdkName: 'VD-VIDEO', legacyDetailIsUndefined: true, legacyEvent: 'VDVideo_continueClicked'}
VD_capture {flow: { documents: {} }, type: 'info', sdkName: 'VD-VIDEO', stage: faceDetection, legacyEvent: 'VDVideo_standardVideoOutput', data: { needsEncoding: false, recording: { video: Blob { size: 11885424, type: 'video/webm;codecs=vp8,opus' } }}
Legacy events¶
To support compatibility with old versions these legacy events are also emitted:
Legacy events will be deprecated in future releases, we recommend moving to the new events as soon as possible.
Event Name | Description | Event Payload |
---|---|---|
VDVideo_mounted | Fired after the SDK mounts correctly. | undefined |
VDVideo_cameraStarted | Fired after the camera on the device is launched correctly. | undefined |
VDVideo_standardVideoRecorderStart | Fired after the standard recorder is properly set and the recording begins. | undefined |
VDVideo_faceDetection | Fired after video recording reach the selfie detection stage. | undefined |
VDVideo_obverseDetection | Fired after video recording reach the detection of document obverse stage. | undefined |
VDVideo_reverseDetection | Fired after video recording reach the detection of document reverse stage. | undefined |
VDVideo_standardVideoRecorderStop | Fired if standard recorder is properly set and after face is not detected on faceDetection stage. Makes recording stops. | undefined |
VDVideo_standardVideoOutput | Fired after video stages are fulfilled. The event object contains the following set of parameters displayed on the table below. | {recording: {…}, xml: File, needsEncoding: false} |
VDVideo_detectionTimeout | Fired after a configurable amount of time. | undefined |
VDVideo_unmounted | Fired after the SDK unmounts. | undefined |
VDVideo_alternativeVideoRecorderStart | Fired after the alternative recorder is properly set and the recording begins. | undefined |
VDVideo_alternativeVideoRecorderStop | Fired if alternative recorder is properly set and after face is not detected on faceDetection stage. Makes recording stops. | undefined |
VDVideo_alternativeVideoOutput | FireD after video stages are fulfilled. The event object contains the following set of parameters displayed on the table below. | {recording: {…}, xml: File, needsEncoding: false} |
VDVideo_restartProcess | Fires after the user changes orientation and clicks the reset button. | undefined |
VDVideo_cameraFailure | Is triggered if the camera on the device fails to launch due to certain circumstances. | undefined |
VDVideo_mountFailure | Fires if SDK fails to mount for any reason. | undefined |
If the configuration logEvents(generic.common.behavior.web.logEvents) is activated, you will see something like the example below in the navigator developer tools, please check carefully the events details if exists:
VDVideo_mounted undefined
VDVideo_initialize: true
VDVideo_orientationStyleChanged has been listened, with detail, {sdkInPortrait: false}
VDVideo_cameraVideoPlayStarted null
VDVideo_prefaceDetection {}
VDVideo_faceDetection recording: { video: Blob { size: 11885424, type: 'video/webm;codecs=vp8,opus' }
VDVideo_continueClicked undefined
VDVideo_unmounted undefined
VD_capture or his legacy event equivalent VDVideo_faceDetection detail flow example¶
- The event details must contain a recorded video and the following details:
data: { needsEncoding: false, recording: { video: { id: 1665135834365, video: { Blob: { size: 4770397, type: "video/webm;codecs=vp8,opus" } }, xml: { File: {} } } }, flow: { documents: { areSmart: true, docRatio: 1.5814814814814815, documentType: 'ID1', documents: {}, inputDocumentsConfig: 'ES2_ID', requiredDocumentSides: [obverse, reverse] } }, legacyDetail: { needsEncoding: false, recording: { video: { id: 1665135834365, video: { Blob: { size: 4770397, type: "video/webm;codecs=vp8,opus" } }, xml: { File: {} } } } }, legacyDetailIsUndefined: false, legacyEvent: "VDVideo_standardVideoOutput", sdkName: "VD-VIDEO", type: "info" }
VD_cameraFailurePermissionError in Safari¶
In safari these permission errors can happen indefinitely, please visit the FAQ page for more information.