API¶

This section details the methods and events available for interacting with the SDK, providing comprehensive control over its functionalities.

Available methods and properties¶

You can obtain an instance of the SDK through a query selector and then leverage the methods outlined below.

/** Get Instance from rendered tag in the DOM */
const VDSelfie = document.querySelector('vd-selfie')

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

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

An instance of the SDK class is also globally available via window.vdSelfie.VDSelfie. This allows you to access static values or perform operations before attaching the SDK to the DOM.

`initializeSdk`¶

This method initializes and configures the SDK. It must be called before using any other SDK functionality.

For a practical usage example, refer to the Initialize installation section.

Parameters¶

config (required) — string | object Defines the properties required to configure the SDK:

If provided as a string, it must be the path to the configuration file.
If provided as an object, it must be a valid configuration object that complies with the defined schema.

See the Configuration object example for reference.

challengeToken (required for active liveness only) — string A JWS token that defines the head movement actions the user must perform.

For a detailed explanation of this parameter and instructions on how to obtain a valid token, refer to the Challenge documentation.

Deprecation Notice¶

The challengeToken parameter can also be included in the configuration object as part of the JSON schema. However, this usage is deprecated and should not be used. It is strongly recommended to provide this value directly as a method parameter.

Return Value¶

Promise<boolean> — Resolves to true if the SDK was successfully initialized.

Example¶

const config = "myAssetsPaths/config.json";
const result: Promise<boolean> = await VDSelfie.initializeSdk(config, challengeToken);

`getJWTChallenge()`¶

This method returns a JWS token to define the head movement actions to perform. It can be used for the initializeSDK method and restartChallenge in case the challenge needs to be restarted.

Example¶

const jws = VDSelfie.getJWTChallenge();

`restartChallenge(challengeToken)`¶

This method restarts the selfie challenge using a new JWS token. Typically used when the current challenge has expired or needs to be refreshed (e.g., after a timeout or cancellation).

Parameters¶

challengeToken (required) — string A JWS token that defines the head movement actions the user must perform.

For details on how to obtain a valid token, refer to the Face Biometry Process with Selfie Alive Pro documentation.

Return Value¶

boolean — Returns true if the token was successfully set and the challenge restarted.

Behavior¶

If the token is valid, the method dispatches the VD_challengeUpdated `event. You can listen for this event to update the UI or trigger any related logic.

Example¶

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

`getPackageVersion()`¶

Retrieves the current version of the SDK.

Return Value¶

string — Returns a string representing the SDK version, in the format x.x.x.

Example¶

const sdkVersion = VDSelfie.getPackageVersion();

`events`¶

A static property that exposes all public SDK event names. Useful for subscribing to and managing SDK-related events dynamically.

Return Value¶

string[] — Returns an array of strings, each representing a public SDK event.

Example¶

const events = window.vdSelfie.VDSelfie.events;
console.log(events); // ['VD_ready', 'VD_challengeUpdated', ...]

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	Event Detail	Event Trigger
VD_mounted	`detail: {"sdkName": "VD-SELFIE", "type": "info", "legacyEvent": "VDAlive_mounted", "legacyDetailIsUndefined": true}`	When the SDK is mounted
VD_loaded	`detail: {"sdkName": "VD-SELFIE", "type": "info", "flowType": "head"}`	When the SDK is fully loaded
VD_instructions	`detail: {"sdkName": "VD-SELFIE", "type": "info", "flowType": "head"}`	When initial instructions are displayed
VD_flowStarted	`detail: {"sdkName": "VD-SELFIE", "type": "info", "flowType": "head"}`	When the capture flow starts
VD_cameraPermissionsGranted	`detail: {"sdkName": "VD-SELFIE", "type": "info", "flowType": "head"}`	When the user grants camera permissions
VD_cameraStarted	`detail: {"sdkName": "VD-SELFIE", "type": "info", "cameraLabels": "camera label", "legacyEvent": "VDAlive_cameraStarted", "legacyDetailIsUndefined": true, "flowType": "selfie"}`	When the camera starts successfully
VD_cameraVideoPlayStarted	`detail: {"type": "info", "sdkName": "VD-SELFIE", "size": {"width": 1920, "height": 1080}, "cameraLabels": "camera label", "legacyDetailIsUndefined": true, "legacyEvent": "VDAlive_cameraVideoPlayStarted", "flowType": "head"}`	When the camera video playback begins
VD_capturedSelfie	`detail: {"flow": "head", "type": "info", "sdkName": "VD-SELFIE", "data": {}, "legacyEvent": "VDAlive_prefaceDetection", "legacyDetail": {}, "stage": "prefaceDetection", "legacyDetailIsUndefined": false, "flowType": "head"}`	When the initial selfie is captured before head movements
VD_cameraRecorderSetup	`detail: {"sdkName": "VD-SELFIE", "isAlternative": false, "mediaRecorderConfig": {...}, "supportedPlayableMimetypes": [], "supportedRecordingMimetypes": [], "legacyDetailIsUndefined": true, "flowType": "head"}`	When the camera recording is configured
VD_headOkMovement	`detail: {"challengeNumber": 1, "movementRequested": "bottom", "sdkName": "VD-SELFIE", "type": "info", "flowType": "head"}`	When a correct head movement is made
VD_headWrongMovementError	detail: {"errorType": "Wrong Head Movement Error", "challengeNumber": 0, "movementRequested": "bottom", "headPosition": "right", "faceRectH": 391.98445892333984, "faceRectW": 252.13288792967796, "faceRectX": 584.2461884915829, "faceRectY": 514.415885925293, "maxPitch": null, "maxRoll": null, "maxYaw": null, "minPitch": null, "minRoll": null, "minYaw": null, "pitchDetected": -15, "rollDetected": 25, "yawDetected": -10, "time_elapsed": 95373.69999999925, "sdkName": "VD-SELFIE", "type": "error", "flowType": "head"}	When an incorrect head movement is detected
VD_headMovementTimeoutError	detail: {"errorType": "No Movement Detected Error", "challengeNumber": 0, "movementRequested": "bottom", "headPosition": "center", "faceRectH": 391.98445892333984, "faceRectW": 252.13288792967796, "faceRectX": 584.2461884915829, "faceRectY": 514.415885925293, "maxPitch": null, "maxRoll": null, "maxYaw": null, "minPitch": null, "minRoll": null, "minYaw": null, "pitchDetected": -15, "rollDetected": 25, "yawDetected": -10, "time_elapsed": 95373.69999999925, "sdkName": "VD-SELFIE", "type": "error", "flowType": "head"}	When a head movement has not been detected
VD_cameraRecorderStop	`detail: {"sdkName": "VD-SELFIE", "_recordedBlob": {}, "isAlternative": false, "alternativeBlob": null, "legacyDetailIsUndefined": true, "flowType": "head"}`	When the camera recording is stopped
VD_capturedHead	`detail: {"type": "info", "sdkName": "VD-SELFIE", "flowType": "head"}`	When the head movement process is completed
VD_successTickFinish	`detail: {"type": "info", "sdkName": "VD-SELFIE", "legacyEvent": "VDAlive_successTickFinish", "legacyDetailIsUndefined": true, "flowType": "head"}`	When the success tick animation finishes
VD_capture	`detail: {"flow": "head", "type": "info", "sdkName": "VD-SELFIE", "data": {}, "legacyEvent": "VDAlive_faceDetection", "legacyDetail": {}, "stage": "faceDetection", "legacyDetailIsUndefined": false, "flowType": "head"}`	When the final capture completes after success tick
VD_processFinished	`detail: {"sdkName": "VD-SELFIE", "type": "info", "legacyDetailIsUndefined": true, "flowType": "head"}`	When the whole process is finished, either successfully or with an error
VD_cameraFailureDefaultError	`detail: {"type": "error", "errorType": "The camera of the device has not started.", "sdkName": "VD-SELFIE", "legacyEvent": "VDAlive_cameraFailureError", "legacyDetailIsUndefined": true, "flowType": "head"}`	When camera can't be initialised for any reason
VD_cameraFailurePermissionError	`detail: {"type": "error", "errorType": "The browser does not accept the permissions of the camera", "sdkName": "VD-SELFIE", "legacyEvent": "VDAlive_cameraFailurePermissionError", "legacyDetailIsUndefined": true, "flowType": "head"}`	When camera permissions are denied
VD_cameraFailureVideoNotFoundError	`detail: {"type": "error", "errorType": "The video has not started on the device.", "sdkName": "VD-SELFIE", "legacyEvent": "VDAlive_cameraFailureVideoNotFoundError", "legacyDetailIsUndefined": true, "flowType": "head"}`	When no usable camera is found to perform the flow
VD_orientationStyleChanged	`detail: {"type": "info", "sdkName": "VD-SELFIE", "data": {"sdkInPortrait": true}, "legacyDetailIsUndefined": false, "legacyDetail": {"sdkInPortrait": true}, "legacyEvent": "VDAlive_orientationStyleChanged", "flowType": "head"}`	When screen orientation changes to an unsupported layout
VD_orientationChanged	`detail: {"data": {"orientation": "landscape"}, "flowType": "selfie", "legacyDetail": {"orientation": "landscape"}, "legacyDetailIsUndefined": false, "legacyEvent": "VDAlive_orientationChanged", "sdkName": "VD-SELFIE", "type": "info"}`	When screen orientation changes to an unsupported layout
VD_faceNotCentered	`detail: {"continuousTimeNotCentered": 1, "sdkName": "VD-SELFIE", "type": "info", "flowType": "head"}`	When the face is detected as not centered
VD_detectionTimeout	`detail: {"sdkName": "VD-SELFIE", "type": "info", "legacyEvent": "VDAlive_detectionTimeout", "legacyDetailIsUndefined": true, "flowType": "head"}`	When the flow ends due to timeout
VD_reviewImage	`detail: {"sdkName": "VD-SELFIE", "type": "info", "legacyEvent": "VDAlive_reviewImage", "legacyDetailIsUndefined": true, "flowType": "selfie"}`	When the review screen is shown
VD_repeatClicked	`detail: {"sdkName": "VD-SELFIE", "type": "info", "legacyEvent": "VDAlive_repeatClicked", "legacyDetailIsUndefined": true, "flowType": "selfie"}`	When the repeat button is clicked in the review screen
VD_closeButtonClicked	`detail: {"sdkName": "VD-SELFIE", "type": "info", "legacyDetailIsUndefined": true, "flowType": "head"}`	When the close button is clicked and user exits from confirmation modal
VD_restartClicked	`detail: {"flowType": "head", "legacyDetailIsUndefined": true, "legacyEvent": "VDAlive_restartClicked", "sdkName": "VD-SELFIE", "type": "info"}`	When the restart button is clicked after feedback screen
VD_restartProcess	`detail: {"sdkName": "VD-SELFIE", "type": "error", "code": 8000, "errorType": "SDK detection fails and should be restarted", "legacyEvent": "VDAlive_restartChallenge", "legacyDetailIsUndefined": true, "flowType": "selfie"}`	When the process needs to be restarted due to an error
VD_restartFromModal	`detail: {"sdkName": "VD-SELFIE", "type": "info", flowType: "head"}`	When the process needs to be restarted after help or error modal
VD_challengeUpdated	`detail: {"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"}`	When the challenge token is updated after an error
VD_processRestarted	`detail: {"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"}`	When the process restarts due to an error
VD_loseFocus	`detail: {"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"}`	When the user has lost the focus on the browser tab.
VD_unmounted	`detail: {"flowType": "selfie", "legacyDetailIsUndefined": true, "legacyEvent": "VDAlive_unmounted", "sdkName": "VD-SELFIE", "type": "info"}`	When the SDK is unmounted
VD_loseFocus	`detail: {"sdkName": "VD-SELFIE", "type": "error", "flowType": "selfie"}`	When the window loses focus

VD_cameraFailurePermissionError in Safari¶

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

API¶

Available methods and properties¶

initializeSdk¶

Parameters¶

Deprecation Notice¶

Return Value¶

Example¶

getJWTChallenge()¶

Example¶

restartChallenge(challengeToken)¶

Parameters¶

Return Value¶

Behavior¶

Example¶

getPackageVersion()¶

Return Value¶

Example¶

events¶

Return Value¶

Example¶

Dispatched events¶

VD_cameraFailurePermissionError in Safari¶

`initializeSdk`¶

`getJWTChallenge()`¶

`restartChallenge(challengeToken)`¶

`getPackageVersion()`¶

`events`¶