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)¶
- 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.
- 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:
- A JPEG image in a Base64 string.
- A recorded video.
- 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.