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
});

destroyVDVideoWidget

• destroyVDVideoWidget: Unmounts the SDK from the target.

• This function must be called like the example below:

window.destroyVDVideoWidget();

getSDKversion

• getSDKversion: Returns an string with the SDK version.

• This function must be called like the example below:

window.vdvideo.getSDKversion();

restartToken

• restartToken: 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.restartToken(jws);

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:

VDVideo_alternativeVideoOutput: Fires after video stages are fulfilled. The event object contains the following set of parameters displayed on the table below.

VDVideo_alternativeVideoRecorderStart: Fires after the alternative recorder is properly set and the recording begins.

VDVideo_alternativeVideoRecorderStop: Fires if alternative recorder is properly set and after face is not detected on faceDetection stage. makes recording stops.

VDVideo_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.

VDVideo_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.

VDVideo_detectionTimeout: Fires after a configurable amount of time.

VDVideo_mounted: Fires after the SDK mounts correctly.

VDVideo_mountFailure: Fires if SDK fails to mount for any reason.

VDVideo_orientationChanged: Fires after user changes device orientation and its detected. The detail property inside the event object contains the current orientation.

VDVideo_restartProcess: Fires after user changes orientation, clicked '?' button or after click continue button at error alert displayed when the time's up at obverse or reverse stage.

VDVideo_standardVideoOutput: Fires after video stages are fulfilled. The event object contains the following set of parameters displayed on the table below.

VDVideo_standardVideoRecorderStart: Fires after the standard recorder is properly set and the recording begins.

VDVideo_standardVideoRecorderStop: Fires if standard recorder is properly set and after face is not detected on faceDetection stage. makes recording stops.

VDVideo_faceDetection: Fires after video recording reach the selfie detection stage.

VDVideo_obverseDetection: Fires after video recording reach the detection of document obverse stage.

VDVideo_reverseDetection: Fires after video recording reach the detection of document reverse stage.

VDVideo_unmounted: Fires after the SDK unmounts.

VDVideo_restartToken: Fires after user changes orientation, clicked '?' button or after click continue button at error alert displayed when the time's up at obverse or reverse stage.

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

VDVideo_mounted 1150 undefined
VDVideo_cameraStarted 3550 {videoWidth: 1280, videoHeight: 720}
VDVideo_orientationChanged 3564 landscape
VDVideo_faceDetection 33140 undefined
VDVideo_standardVideoRecorderStart 33140 undefined
VDVideo_obverseDetection 38303 undefined
VDVideo_reverseDetection 52576 undefined
VDVideo_standardVideoOutput 67618 {recording: {…}, xml: File, needsEncoding: false}
VDVideo_unmounted 69070 undefined

Event camera failure (VDVideo_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('VDVideo_cameraFailure', handleCameraFailureEvent, false);

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

Example:

Video permission error:

• event.type: VDVideo_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