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

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

/** Call restartChallenge  method */
VDSelfie.restartChallenge()

Note that an instance of the class is also available in window.vdSelfie.VDSelfie, and you could use it before attaching it to the DOM, for example, to check the static values.

initializeSdk(config, aliveChallenge)

  • @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.
    • aliveChallenge: {string} It is required only when using SAP flow. Its value is a jws token that contains the head movement actions which are asked to be performed to the user. For better understanding of this parameter and to know how to get a valid challenge token, please check the following link.

    Note aliveChallenge (token) parameter is also available as a json schema configuration parameter. However, it is deprecated and must not be used.

  • @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 VDSelfie.initializeSdk(config, aliveChallenge);

restartChallenge(aliveChallenge)

  • This method is used to restart the selfie challenge token.
  • @Params

    • aliveChallenge: {string} Its value is a jws token that contains the head movement actions which are asked to be performed to the user. For better understanding of this parameter and to know how to get a valid challenge token, please check the following link.
  • @Return

    • {Boolean} The function returns a boolean that informs if the jwt token has been setup correctly.

How to use

If the challenge or token (jws) is correctly set, the restartChallenge function dispatch an event called VD_challengeUpdated.

const jws = VDSelfie.getJWTChallenge(); 
VDSelfie.restartChallenge(jws);

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.vdSelfie.VDSelfie.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 = VDSelfie.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, legacyDetailIsUndefined: boolean}
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, legacyDetailIsUndefined: boolean}
VD_cameraRecorderSetupError Fired after the camera encoder in the browser API has not been configured correctly or an error has been found during the setup. detail:{type: string, errorType: string, sdkName: string, legacyEvent: string, legacyEvent: string, legacyDetailIsUndefined: boolean}
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 video stream from the camera on the device is loaded correctly. detail:{type: string, sdkName: string, legacyEvent: string, legacyDetailIsUndefined: boolean, cameraLabels: string, size: { width: number, height: number}}
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_capture Fired after successful detection. The detail property inside the event object contains properties with the captured results. The stage property that has the detail indicates in which part of the process the event has been launched. detail:{flow:string, type: string, stage: string, sdkName: string, legacyEvent: string, legacyDetailIsUndefined: boolean, legacyDetail:{image, image_alive, webVTT}, data:{image, image_alive, webVTT}}
VD_challengeUpdated Fired when the challenge restarts, one new head movement is set to complete the challenge. detail:{type: string, sdkName: string}
VD_closeButtonClicked Fired after the close button is clicked. detail:{sdkName: string, type: 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_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, legacyEvent: string, legacyDetailIsUndefined: boolean}
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, legacyDetailIsUndefined: boolean, data:{orientation: string}, 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: 8000 (InvalidSelfieToken), 8001 (ErrorChallenge), or 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:{sdkName: string, type: 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-SELFIE', type: 'info', legacyDetailIsUndefined: true, legacyEvent:'VDAlive_mounted' }
VD_unmounted {sdkName: 'VD-SELFIE', type: 'info', legacyDetailIsUndefined: true, legacyEvent:'VDAlive_unmounted'}
VD_cameraVideoPlayStarted {sdkName: 'VD-SELFIE', type: 'info', cameraLabels: 'FaceTime HD Camera (3A71:F4B5)', legacyDetailIsUndefined: true, legacyEvent:'VDAlive_cameraVideoPlayStarted'}
VD_continueClicked { type: 'info', sdkName: 'VD-SELFIE', legacyDetailIsUndefined: true, legacyEvent: 'VDAlive_continueClicked'}
VD_capture {flow: 'head', type: 'info', sdkName: 'VD-SELFIE', stage: faceDetection, legacyEvent: 'VDAlive_capture', data: {image:"data:image/jpeg;base64,/9j/4gvw//Z",image_alive: Blob {size: 1567863, type: 'video/webm;codecs=vp8'}, webVTT: "WEBVTT Kind: metadata\n\n1\n00:00:0.000 --> 0:0:05.345"}}

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
VDAlive_cameraFailureDefaultError Fired if the camera on the device fails to launch. undefined
VDAlive_cameraFailurePermissionError Fired when the user does not accept the camera permissions in the browser. undefined
VDAlive_cameraFailureVideoNotFoundError Fired if the video on the device fails to launch. undefined
VDAlive_cameraStarted Fired after the camera on the device is launched correctly. undefined
VDAlive_cameraVideoPlayStarted Fired after the video stream from the camera on the device is loaded correctly. undefined
VDAlive_closeButtonClicked Fired after the close button is clicked. undefined
VDAlive_continueClicked Fired after the user clicks the continue button in image review screen. undefined
VDAlive_detectionTimeout Fired after a configurable amount of time. undefined
VDAlive_faceDetection Fired after successful detection of the selfie flow selected. The detail property inside the event object contains an image and other media with the capture. detail:{image: string, image_alive: [null, string, Blob, IVideoRecorderBlob ], webVTT: string}
VDAlive_mounted Fired after the SDK mounts correctly. undefined
VDAlive_mountFailure Fired if SDK fails to mount for any reason. undefined
VDAlive_orientationChanged Fired after the user changes the orientation of the device to update all the styles of the SDK. detail:{ orientation: string }
VDAlive_orientationStyleChanged Fired after orientation style changes. detail:{sdkInPortrait: boolean}
VDAlive_prefaceDetection Fired after successful detection of the face. detail:{ image: string }
VDAlive_repeatClicked Fired after the user clicks the repeat button in image review screen. undefined
VDAlive_restartChallenge Fired after alive challenge head detection fails and should be restarted. undefined
VDAlive_restartClicked Fired after the user clicks in the repeat button, changes the device orientation or any error happens. undefined
VDAlive_successTickFinish Fired after success tick finish. undefined
VDAlive_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:

VDAlive_mounted  undefined
VDAlive_initialize: true
VDAlive_orientationStyleChanged has been listened, with detail, {sdkInPortrait: false}
VDAlive_cameraVideoPlayStarted  null
VDAlive_prefaceDetection {}
VDAlive_faceDetection  {image: 'data:image/jpeg;base64,/9j/4QUTRXhpZgAATU0AKgAAAAg…AeveGBVU5PaFq9dvcMcv6pd8RnKswkKOngiSs8ZLyjob/2Q==', image_alive: Blob, webVTT: 'WEBVTT Kind: metadata\n\n1\n00:00:00.000 --> 00:00:02…e":"action-1","parameters":{"direction":"top"}}}\n'}
VDAlive_continueClicked  undefined
VDAlive_unmounted  undefined

VD_capture or his legacy event equivalent VDAlive_faceDetection detail flows examples

Selfie - Selfie

  • The event details must contain just one JPEG image in a Base64 string:
VDAlive_faceDetection {image: 'data:image/jpeg;base64,/9j/4QUTRXhpZgAATU0AKgAAAAg…AeveGBVU5PaFq9dvcMcv6pd8RnKswkKOngiSs8ZLyjob/2Q==', image_alive: null, webVTT: null}

Selfie - Head

  • The event details must contain:
  1. A JPEG image in a Base64 string.
  2. A recorded video.
  3. A webVTT file containing information about the head movements challenge.
    # BLOB type
    VDAlive_faceDetection  {image: 'data:image/jpeg;base64,/9j/4QUTRXhpZgAATU0AKgAAAAg…AeveGBVU5PaFq9dvcMcv6pd8RnKswkKOngiSs8ZLyjob/2Q==', image_alive: Blob, webVTT: 'WEBVTT Kind: metadata\n\n1\n00:00:00.000 --> 00:00:02…e":"action-1","parameters":{"direction":"top"}}}\n'}
    
    # IVideoRecorderBlob type
    VDAlive_faceDetection  { image: 'data:image/jpeg;base64,/9j/4QUTRXhpZgAATU0AKgAAAAg…AeveGBVU5PaFq9dvcMcv6pd8RnKswkKOngiSs8ZLyjob/2Q==', 
    image_alive: {
        recording: {
            id: 1665135834365,
            video: {
                frames: [
                    {
                        "data": "/9j/4AAQSkZJRgABAQAAAQABAAD/4gIoSUNDX1BST0ZJTEUAAQEAAAIYAAAAAA",
                        "position": 1,
                        "time": 0.101
                    },
                ],
                fps: 9.878244888582588,
                duration: 4.353
            },
            audio: ""
        },
        needsEncoding: true
    }, 
    webVTT: 'WEBVTT Kind: metadata\n\n1\n00:00:00.000 --> 00:00:02…e":"action-1","parameters":{"direction":"top"}}}\n'}
    

VD_cameraFailurePermissionError in Safari

In safari these permission errors can happen indefinitely, please visit the FAQ page for more information.