API¶

Available methods¶

This methods allow to control the SDK, and are available in the window object:

sdkStart¶

sdkStart: Method that mounts and initializes the SDK, for more details check Introduction and Customization sections.

This function must be called like the example below:

window.sdkStart({
  // ... configuration goes here
});

restartChallenge¶

restartChallenge: This methods is used to restart the video token and returns void, it needs a JWS provided, please review the link for get a challenge from validas.

This function must be called like the example below:

const jws = getJWS();
window.restartChallenge(jws);

destroyVDAliveWidget¶

destroyVDAliveWidget: Unmounts the SDK from the target.

This function must be called like the example below:

window.destroyVDAliveWidget();

getSDKversion¶

getSDKversion: Returns an string with the SDK version.

This function must be called like the example below:

window.vdalive.getSDKversion();

Dispatched events¶

The SDK will dispatch a set of events to communicate that some actions has been performed, the events are dispatched by the SDK in this manner event_name time elapsed from page load details:

VDAlive_cameraFailure: Is triggered if the camera on the device fails to launch due to certain circumstances. These circumstances are explained in the next section. The detail property inside the event object contains the error thrown.
VDAlive_cameraStarted: Fires after the camera on the device is launched correctly. The detail property inside the event object contains the videoWidth and videoHeight of the video stream, which in turn informs of the aspect ratio of the widget.
VDAlive_detectionTimeout: Fires after a configurable amount of time.
VDAlive_orientationChanged: Fires after user changes device orientation and its detected. The detail property inside the event object contains the current orientation.
VDAlive_prefaceDetection: Fires after successful detection of the face. The detail property inside the event object contains a base64 png with the capture.
VDAlive_faceDetection: Fires after successful detection of the smile. The detail property inside the event object contains a base64 png with the capture.
VDAlive_repeatClicked: Fires after user clicks repeat button in review image.
VDAlive_continueClicked: Fires after user clicks continue button in review image.
VDAlive_mounted: Fires after the SDK mounts correctly.
VDAlive_mountFailure: Fires if SDK fails to mount for any reason.
VDAlive_unmounted: Fires after the SDK unmounts.
VDAlive_restartChallenge: Fires after the user restart de challenge process.
VDAlive_modelLoaded: Fires after user's face is detected with an initial emotion for smile process.

If the configuration logEventsToConsole is activated, you will see something like the example below in the navigator developper tools:

VDAlive_mounted 2205 undefined
VDAlive_cameraStarted 2550 Object
VDAlive_prefaceDetection 17968 undefined
VDAlive_faceDetection 27370 {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 27371 undefined
VDAlive_unmounted 28419 undefined

Event camera failure (VDAlive_cameraFailure)¶

As stated in the previous section, there are several circumstances in which the camera may fail. You will probably want to perform a logic depending on each circumstance. Here is an example of how we might listen to each case, as well as the respective explanation.

How to listen to the event¶

addEventListener('VDAlive_cameraFailure', handleCameraFailureEvent, false);

function handleCameraFailureEvent(event) {
  // action to do
  console.info(event.type, event.detail)
}

Example:

Video permission error:

event.type: VDAlive_cameraFailure

event.detail: NotAllowedError: Permission denied

Types of video errors¶

The event object will have one of the following thrown errors inside:

Video not found¶

Error to display to user if media device is not found.

Message to user display:

'Please check that the device has a camera'

Types of event detail:

NotFoundError:

Thrown if no media tracks of the type specified were found that satisfy the given constraints.

DevicesNotFoundError

Video unavailable¶

Error to display to user if media device is unavailable.

Message to user display:

'Please check that the device camera is not being used by another program'

Types of event detail:

NotReadableError:

Thrown if, although the user granted permission to use the matching devices, a hardware error occurred at the operating system, browser, or Web page level which prevented access to the device.

TrackStartError:

Is a non-spec Chrome-specific version of NotReadableError.

CameraInUseError

SourceUnavailableError:

Failed to allocate videosource.

Video constraint error¶

Error to display to user if media constraint is not correct.

Message to user display:

'Please check that the device has a camera with a minimum resolution of 640 x 480'

Types of event detail:

OverconstrainedError:

Thrown if the specified constraints resulted in no candidate devices which met the criteria requested. The error is an object of type OverconstrainedError, and has a constraint property whose string value is the name of a constraint which was impossible to meet, and a message property containing a human-readable string explaining the problem.

Note: Because this error can occur even when the user has not yet granted permission to use the underlying device, it can potentially be used as a fingerprinting surface.

ConstraintNotSatisfiedError:

The resolution constraints is not supported by the device.

Video permission error¶

Error to display to user if media does not have permission.

Message to user display: 'Please allow the page to access the camera'

Types of event detail:

NotAllowedError:

Thrown if one or more of the requested source devices cannot be used at this time. This will happen if the browsing context is insecure (that is, the page was loaded using HTTP rather than HTTPS). It also happens if the user has specified that the current browsing instance is not permitted access to the device, the user has denied access for the current session, or the user has denied all access to user media devices globally. On browsers that support managing media permissions with Feature Policy, this error is returned if Feature Policy is not configured to allow access to the input source(s).

Note: Older versions of the specification used SecurityError for this instead; SecurityError has taken on a new meaning.

PermissionDeniedError:

Permissions have not been granted to use the camera and microphone, you need to allow the page access to your devices in order for the demo to work.

SecurityError:

Thrown if user media support is disabled on the Document on which getUserMedia() was called. The mechanism by which user media support is enabled and disabled is left up to the individual user agent.

Video external input error¶

Error to display to user if a virtual camera is the input device.

Message to user display:

'Please check that you do not have any software simulating the camera'

Types of event detail:

ExternalInputError

Video protocol error¶

Error to display to user if the connection is HTTPS.

Message to user display:

'Please check that a secure connection has been established between the server and the client (HTTPS)'

Types of event detail:

HTTPSError

Video default error¶

Error to display to user if there is a media default error.

Message to user display:

'Sorry, there was an error starting the camera'

Types of event detail:

TargetSizeDimensionsError
AbortError:

Although the user and operating system both granted access to the hardware device, and no hardware issues occurred that would cause a NotReadableError DOMException, throw if some problem occurred which prevented the device from being used.

TypeError:

Thrown if the list of constraints specified is empty, or has all constraints set to false. This can also happen if you try to call getUserMedia() in an insecure context, since navigator.mediaDevices is undefined in an insecure context.

Others