Skip to content

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)

  • @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.