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 VDDocument = document.querySelector('vd-document')

/** Call initializeSdk method */
VDDocument.initializeSdk()

Note that an instance of the class is also available in window.vdDocument.VDDocument, 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 VDDocument.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.vdDocument.VDDocument.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 = VDDocument.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_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:string, type: string, sdkName: string, legacyEvent: string, legacyDetailIsUndefined: boolean, legacyDetail: string, data:{obverse: string, documentId: string, documentSide: string, documentType: string, manualCapture: boolean, shouldUnmount: boolean}}
VD_closeButtonClicked	Fired after the close button is clicked.	detail:{type: string, sdkName: string, legacyEvent: string, legacyDetailIsUndefined: boolean}
VD_continueClicked	Fired after the user clicks the continue button in image review screen.	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_manualCaptureButton	Fired after the user clicks the circular button that appears to the right of the rectangle to do the manual capture.	detail:{type: string, sdkName: string}
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_repeatClicked	Fired after the user clicks the repeat button in image review screen.	detail:{sdkName: string, type: string, legacyEvent: string, legacyDetailIsUndefined: boolean}
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}
VD_reviewImage	Fired when review view is displayed.	detail:{type: string, sdkName: string, legacyEvent: string, legacyDetailIsUndefined: boolean}

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-DOCUMENT', type: 'info'}
VD_unmounted {sdkName: 'VD-DOCUMENT', type: 'info'}
VD_cameraStarted {sdkName: 'VD-DOCUMENT', type: 'info'}
VD_cameraVideoPlayStarted {type: 'info', sdkName: 'VD-DOCUMENT', size: {…}, cameraLabels: 'ManyCam Virtual Webcam (pleV:ideo),FaceTime HD Camera (3A71:F4B5)', legacyDetailIsUndefined: true,legacyEvent:null, sdkName:"VD-DOCUMENT", size:height:1080, width:1920, type:"info"}
VD_continueClicked {type: 'info', sdkName: 'VD-DOCUMENT', legacyEvent: 'VDDocument_continueClicked'}
VD_successTickFinish {type: 'info', sdkName: 'VD-DOCUMENT', legacyEvent: undefined, legacyDetailIsUndefined: true}
VD_continueClicked {type: 'info', sdkName: 'VD-DOCUMENT', legacyEvent: 'VDDocument_continueClicked', legacyDetailIsUndefined: true}
VD_capture 
{ 
  flow: 'document', 
  type: 'info', 
  sdkName: 'VD-DOCUMENT', 
  stage: 'obverseDetection'
  data:{
      documentId:"ES_IDCard_2021",
      documentSide:"OBVERSE",
      documentType:"ID1",
      manualCapture:false,
      obverse:"data:image/jpeg;base64,/9j/4QjZRXhpZgAATU0AKgAAAA...",
      shouldUnmount:false
  },
  legacyDetail: "data:image/jpeg;base64,/9j/4QjZRXhpZgAATU0AKgAAAA...",
  legacyDetailIsUndefined: false,
  legacyEvent: "VDDocument_obverseDetection",
}

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
VDDocument_cameraFailureError	Fires if the camera on the device fails to launch.	undefined
VDDocument_cameraStarted	Fires after the camera on the device is launched correctly.	undefined
VDDocument_continueClicked	Fires after the user clicks the continue button in image review screen.	undefined
VDDocument_detectionTimeout	Fires after a configurable amount of time.	undefined
VDDocument_mounted	Fires after the SDK mounts correctly.	undefined
VDDocument_mountFailure	Fires if SDK fails to mount for any reason.	undefined
VDDocument_obverseDetection	Fires after successful detection of document obverse. The detail property inside the event object contains a base64 png with the capture.	detail:{ base64: string }
VDDocument_obverseDetection_type	Fires after successful detection of document obverse. The detail property inside the event object contains an Array of strings with the name of the detected documents.	detail:{ type: string }
VDDocument_orientationChanged	Fires after the user changes device orientation and it's detected. The detail property inside the event object contains the current orientation.	detail:{ orientation: string }
VDDocument_repeatClicked	Fires after the user clicks the repeat button in the image review screen.	undefined
VDDocument_restartProcess	Fires after the SDK restart process.	undefined
VDDocument_reverseDetection	Fires after successful detection of document reverse. The detail property inside the event object contains a base64 png with the capture.	detail:{ image: string }
VDDocument_reverseDetection_type	Fires after successful detection of document reverse. The detail property inside the event object contains a Array of strings with the name of the detected documents.	detail:{ type: string }
VDDocument_reviewImage	Fires after the SDK shows the image review screen.	undefined
VDDocument_trackEnded	Fires if the camera on the device fails during the detection process and the media track is ended. The detail property inside the event object contains the error thrown.	undefined
VDDocument_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.	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:

VDDocument_mounted  undefined
VDDocument_orientationChanged has been listened, with detail, {sdkInPortrait: false}
VDDocument_cameraVideoPlayStarted  undefined
VDDocument_obverse {image: 'data:image/jpeg;base64,/9j/4QUTRXhpZgAATU0AKgAAAAg…AeveGBVU5PaFq9dvcMcv6pd8RnKswkKOngiSs8ZLyjob/2Q=='}
VDDocument_continueClicked  undefined
VDDocument_unmounted  undefined

VD_capture

This event is dispatched after the successful capture of the document. It has two equivalent legacy events: VDDocument_obverseDetection and VDDocument_reverseDetection.

The detail event includes the following data:

• documentId: the unique identifier of the document (e.g., ES_IDCard_2015).
• documentSide: the face of the document, specifies whether the captured image is of the obverse or reverse side of the document.
• documentType: the type or size of document. This identifier (size) can correspond to multiple documents (e.g., ID1).
• manualCapture: indicates whether the document was captured manually.
• observe or reverse: the captured image of the document, encoded in Base64 format.
• shouldUnmount: specifies if the SDK should be unmounted after capturing the document.

Additionally, it contains the following information:

• flow: the current flow of the SDK.
• type: indicates the type of event (informative, error, etc.).
• sdkName: the name of the SDK.
• legacyEvent: name of the legacy event.
• legacyDetail: detail of the legacy event. The captured image of the document, encoded in Base64 format.
• legacyDetailIsUndefined: indicate if the legacy event has data in legacyDetail.

The structure of the object is shown:

  event.detail:{
    flow: string, 
    type: string, 
    sdkName: string, 
    legacyEvent: string,
    legacyDetail: string,
    legacyDetailIsUndefined: boolean,
    data: {
      obverse: string, # when we capture the front 
      reverse: string, # when we capture the rear
      documentId: string, 
      documentSide: string, 
      documentType: string, 
      manualCapture: boolean, 
      shouldUnmount: boolean
    }
  }

An example VD_capture response would be the following:

  VD_capture {
    flow: "document",
    type: "info",
    sdkName: "VD-DOCUMENT",
    stage: 'obverseDetection'
    legacyEvent: "VDDocument_obverseDetection",
    legacyDetail: "data:image/jpeg;base64,/9j/4QVDRXhpZgAATU0AKgAAAA",
    legacyDetailIsUndefined: false,
        data: {
          documentId: "ES_IDCard_2015",
          documentSide: "OBVERSE",
          documentType: "ID1",
          manualCapture: false,
          obverse: "data:image/jpeg;base64,/9j/4QVDRXhpZgAATU0AKgAAAA",
          shouldUnmount: false
        },
  }