The KeylessAuth and KeylessEnroll classes emit 2 kind of error events:
The all purpose "error" event
The WebSocket specific "ws-error" event
Here's an example of how to handle these errors:
import { KeylessAuth } from '@keyless/sdk-web'
const auth = new KeylessAuth()
auth.on('error', (error) => {
// handle error
})
auth.on('ws-error', (event, error) => {
// handle error
// the event argument is the one emitted by the native WebSocket instance
})
// connecting without a WebSocket URL and username will of course emit an error
auth.connect()
Of course this example also applies to the KeylessEnroll class, each error contains the error code in the message, this is the enum which is also exported by the @keyless/sdk-web package:
Forwarded from the native WebSocket instance “error” event.
WEB_SOCKET_OPEN
Triggered by creating a new native WebSocket instance, could also be caused by a timeout during the connection to the WebSocket.
WEB_SOCKET_UNEXPECTED_CLOSE
Triggered after the “ws-close” event, it is triggered when the WebSocket closes in a state where it is not supposed to be closing.
BeginImageStream
ImageAccepted
StopSending
This is the list of events which are considered as unexpected if the WebSocket closes.
WEB_SOCKET_TIMEOUT
Triggered after the WebSocket connection is open for the specified amount of time, by default this timeout is 1 minute.
KEY_UNSET
Triggered when the key.value has not been provided to the KeylessAuth connect options.
KEY_ID_UNSET
Triggered when the key.id has not been provided to the KeylessAuth connect options.
USERNAME_UNSET
Triggered when the username has not been provided to the KeylessAuth connect options.
ERROR
Triggered by the WebSocket Error incoming message, the full error can be found inside the event argument of the "error" event.
LIVENESS_FAILED
Triggered by the WebSocket LivenessFailed incoming message, as the name implies it means the frames sent by the user did not pass our liveness.
USERNAME_LOCKED_OUT
Triggered when the lockout policy is enabled and the user has failed the specified amount of times in a row the authentication or enrollment.
The user will be locked out for the specified amount of time, which by default is 5 minutes.
The user will be locked out after the specified amount of times in a row, which by default is 5 attempts.
IMAGE_STREAM_FAILED_TO_DRAW_FRAME
Triggered when it is impossibile to draw the video stream frame, this could happen for various reasons:
The user did not grant camera permissions, so there is no stream to draw from.
The browser does not support Canvas or ImageCapture APIs, should be unlikely.
The video stream is absent or undefined for unknown reasons.
ENROLL_USER_EXISTS
Triggered by the WebSocket UserDoesExist incoming message, as the name implies it means that the user is trying to enroll but they are already enrolled with that username.
AUTH_USER_DOES_NOT_EXIST
Triggered by the WebSocket UserDoesNotExist incoming message, as the name implies it means that the user is trying to authenticate with a username that has not been enrolled first.
AUTH_RECOGNITION_FAILED
Triggered by the WebSocket FinishedAuthentication incoming message when the result is FAILURE, as the name implies it means that the user face did not match with the face that was enrolled.
Web Components Error Handling
Handling errors in the web components is very similar to how they are handled in the @keyless/sdk-web library, so check out that part first because those errors are inherited by the web components: Errors Explanation
Of course the web components naturally have more complexity, let’s go in order with some examples on how to handle all the errors emitted by the web components.
Triggered when there are no media devices capable of video output, this means that the user either does not have a camera or they did not grant the camera permissions.
NO_MEDIA_STREAM
Triggered when there is no media stream available, explanation is the same as NO_MEDIA_DEVICES error.
CAMERA_CHECK_FAILED
Triggered when camera checks are enabled and the user failed to meet the requested conditions.
The "ws-error" event is emitted when the WebSocket native instance emits an error, here's an example:
We use a custom error here called WebSocketErrorEvent which contains both the native WebSocket event and the error generated by us with a predictable error code.
The "finished" event is a bit special, meaning that in the authentication flow the integrator must check whether the authentication result was successful or not, here's an example:
The "user-does-not-exist" event is only emitted by the authentication web components, it’s a straight failure due to the user not existing on the server.
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Auth</title>
<style>
* {
box-sizing: border-box;
}
body {
align-items: center;
display: flex;
justify-content: center;
margin: 0;
min-height: 100vh;
padding: 8px;
}
kl-auth {
border: 1px solid lightgray;
}
</style>
</head>
<body>
<kl-auth
enable-camera-instructions
key="IMAGE_ENCRYPTION_PUBLIC_KEY"
key-id="IMAGE_ENCRYPTION_KEY_ID"
lang="en"
size="375"
theme="light"
username="USERNAME"
ws-url="KEYLESS_AUTHENTICATION_SERVICE_URL"
></kl-auth>
<script src="@keyless/sdk-web-components/elements/auth/auth-element.iife.js"></script>
<script>
const auth = document.querySelector('kl-auth')
auth.addEventListener('user-does-not-exist', (event) => {
// handle feedback to the user about his username being wrong or
// his account not potentially existing
})
</script>
</body>
</html>
The "user-exists" event is only emitted by the enrollment components, if a user attempts to enroll with a username that is already enrolled on the server, this event will be emitted.
