API Reference

Complete reference for the Azakaw Liveness Web SDK API.

Component Properties

Inputs

Input	Type	Default	Required	Description
session-id	string	null	yes	A short-lived session identifier minted by your backend. The SDK validates it server-side before starting capture.
host-origin	string	null	optional	The URL on which your web application is hosted.
environment	LivenessEnvironment (Sandbox | Production)	Production	optional	Target environment for the liveness session.
region	LivenessRegion (KSA | Qatar | UAE)	UAE	optional	Region in which the liveness session is processed.

Events

Event Name	Returns	Description
livenessChangeAction	AzakawLivenessEvent	Fired on liveness Actions
success	AzakawLivenessResult	Fired when the user successfully completes the liveness check
failed	AzakawLivenessResult	Fired when the liveness check fails

AzakawLivenessResult

The payload returned by the success and failed events. On a failed check, image and estimatedAge are null.

Properties	Type	Description
status	confirmed | not_confirmed | unknown	Outcome of the liveness check.
sessionId	string	The session identifier associated with the liveness check.
transactionId	string	The unique transaction identifier for this liveness attempt.
estimatedAge	string | null	The estimated age of the user. null when the liveness check fails.
image	string | null	The captured selfie image (base64). null when the liveness check fails.

Actions

Event Name	Description
ELEMENT_VISIBLE	The component is appended to the DOM.
PRESS_START_BUTTON	The "Get started" button is pressed.
PRESS_RETRY_BUTTON	The "Retry" button is pressed.
CLOSE	The "Close" button is pressed.
PROCESS_FINISHED	The component has finished its work.
SERVICE_INITIALIZED	The component has started its work.
RETRY_COUNTER_EXCEEDED	The component has finished its work because the number of transaction attempts was exceeded.

Translation

The list of labels used in the component:

Label	Default message in en locale
showOnlyOneFace	Make sure there is only one face on the screen.
preparingCamera	Preparing the camera...
allowAccessCamera	Allow access to the camera
somethingWentWrong	Something went wrong
incorrectCameraId	No camera with the specified ID found.
checkCameraId	Check if the specified camera ID is correct.
preparingService	Preparing the service...
allowAccessToCamera	Allow access to the camera and reload this page to continue.
error	Error!
versionNotSupported	Your browser version is not supported.
updateBrowser	Update your browser version
licenseError	A license error has occurred
licenseExpired	The license cannot be found or has expired
onlyPortraitOrientation	Portrait orientation only
turnDeviceIntoPortrait	Please turn your device into portrait mode
tryAgain	Try again
noCameraAvailable	No camera available
checkCameraConnection	Check the camera connection and try again.
lookStraight	Look straight
fitYourFace	Center your face
moveCloser	Move closer
moveAway	Move away
holdSteady	Hold steady
takeAPhoto	Take a selfie
processing	Processing...
retryButtonText	Retry
followGuidelinesText	But please follow these guidelines:
letsTryAgainTitle	Let's try that again
noCameraPermission	Camera unavailable!
goButton	Go
selfieTime	Selfie time!
ambientLighting	Ambient lighting is not too bright or too dark and there are no shadows or glare on your face
noMaskSunglassesHeaddress	Neutral facial expression (no smiling, eyes open and mouth closed), no mask, sunglasses or headwear
turnHead	Turn your head a bit
centerFaceTurnHead	Center your face, turn your head
centerFace	Center your face
errorCode	Error code:
illumination	Good illumination.
cameraLevel	Camera at eye level.
noAccessories	No accessories: glasses, mask, hat, etc.
getReady	Get ready
removeOcclusion	Remove items covering your face
tooMuchTurn	Avoid turning your head too much. A small turn is enough.
turnHeadUp	Turn head up a bit to look straight
turnHeadDown	Turn head down a bit to look straight
turnHeadLeft	Turn head left a bit to look straight
turnHeadRight	Turn head right a bit to look straight
configurationErrorTitle	Configuration error
configurationErrorMessage	Please provide a session-id on the <azakaw-liveness> element.
sessionExpiredTitle	Session expired
sessionExpiredMessage	The authenticated session is no longer valid.
connectionErrorTitle	Connection error
connectionErrorMessage	We could not reach the Azakaw service. Please check your connection and try again.
initializingSession	Initializing secure session…
retryAction	Retry
startNewSessionAction	Start a new session

Settings

Here are all the available settings:

Setting	Info	Data type	Default value	Values	Used in
locale	Language of the component. The value is determined based on the following priority: 1. locale component attribute takes the highest priority if explicitly set. 2. If locale is not set, the system checks the html.lang attribute. 3. If no html.lang attribute is available, the system attempts to determine the language from window.navigator. 4. If none of the above are available, the default value en is used.	string	en	ru, en, de, pl, it, hu, zh, sk, uk, fr, es, pt, ar, nl, id, vi, ko, ms, ro, el, tr, ja, cs, th, hi, bn, he, fi, sv, da, hr, no, uz	azakaw-liveness, face-capture
cameraId	Ability to select a camera by defining the camera ID.	string	undefined	camera id string value	azakaw-liveness, face-capture
changeCamera	Whether to show the "Camera Switch" button. Note that if livenessType = 0 (active liveness), the button will not be displayed on mobile devices regardless of the changeCamera setting.	boolean	true	true, false	azakaw-liveness, face-capture
startScreen	Whether to show the Start screen with video instructions. If true, the start screen is shown. If false, no start screen is shown and instead the camera of the device is turned on automatically to capture a face.	boolean	true	true, false	azakaw-liveness, face-capture
finishScreen	Whether to show the Result screen (success screen, retry-screen). If true, the Result screen is shown to the user. If false, no Result screen is displayed, and, during a single session, the user has only one attempt to pass the liveness assessment. In cases where finishScreen is set to false, we recommend monitoring the Events associated with the liveness assessment and then displaying relevant information to the user based on those events. This approach ensures that the user receives necessary feedback even though the Result screen is not displayed by the component itself.	boolean	true	true, false	azakaw-liveness, face-capture
closeDisabled	Whether to disable the "Close" button of the component. If set to true, the "Close" button is hidden from the user.	boolean	false	true, false	azakaw-liveness, face-capture
recordingProcess	Whether to enable a video recording of the process. If set to 0, the video is sent to the server with an additional request. If set to 1, the video is sent to the server with the liveness package. If set to 2, the video isn't sent. The video format depends on the browser: MP4 for Safari, WEB for other browsers.	number	0	0, 1, 2	azakaw-liveness
tag	The server generates a unique identifier for each session before starting a verification process. Using tag, you can set a custom value. Make sure that tag is unique for each session.	string	undefined	any unique for each session	azakaw-liveness
retryCount	Using the retryCount setter, you can set the number of liveness transaction attempts for the user. Once the attempts are exhausted, the component will display a white screen and throw the "RETRY_COUNTER_EXCEEDED" event. By default, the number of attempts is unlimited. Setting the value to 0 removes the limit on the number of attempts, while any positive number limits the attempts.	number	undefined	number of the attempts count	azakaw-liveness
headers	Before starting the camera capture, the component sends a start request to the server and receives the initialization data in response. Once the component successfully completes two stages of verification, it sends the received data to the API for processing. You can use the headers setter to set the headers for the HTTP POST method. Additionally, the video recording is transmitted to the server along with these headers.	object	undefined	object with headers (key, value).	azakaw-liveness
customization	You can customize the element's color, font, and image by using this object. See the Customization section below.	object	undefined	object with customization settings	azakaw-liveness, face-capture
nonce	You can set a unique nonce value to maintain the CSP policy.	string	undefined	unique nonce value	azakaw-liveness, face-capture
rotationAngle	Desktop only. By using the rotationAngle setter, you can specify an angle to compensate for the rotation of your physical camera. When set to values of 90 and -90, the component's design will switch to a mobile (vertical) orientation.	number	undefined	0,180,90,-90	azakaw-liveness, face-capture
holdStillDuration	For the Capture screen, sets the duration that the user needs to stand straight and look at the camera.	number	undefined	seconds	face-capture
timeoutInterval	Timeout for the Capture screen.	number	undefined	seconds	face-capture
livenessType	You can choose a scenario for the liveness assessment. 0 - active liveness, full process that requires head rotation; 1 - passive liveness, a person is asked to only take a selfie, no head rotation required.	number	0	0, 1	azakaw-liveness
detectOcclusion	Whether to disable the face occlusion hint.	boolean	true	true, false	face-capture
tenant	A label used to group transactions by specific customers, applications, or other criteria.	string	undefined	tenant	azakaw-liveness
env	A label used to differentiate transactions by development stages.	string	undefined	env	azakaw-liveness
captureButton	Whether to enable user-triggered capture. Shows the Capture button; desktop layout height increases accordingly. When enabled, the shot is taken only on user action.	boolean	false	true, false	azakaw-liveness, face-capture

Customization

You can customize the color of some elements, fonts, and images with the help of the customization field in the settings object. The customization settings are the following:

Setting	Info	Migrate from	Data type	Default value
fontFamily	Font.	--font-family	string	Noto Sans, sans-serif
fontSize	Base font size.	--font-size	string	16px
onboardingScreenStartButtonBackground	Instruction screen button background color.	--main-color	string	#7E57C5
onboardingScreenStartButtonBackgroundHover	Instruction screen button background hover color.	--hover-color	string	#7C45B4
onboardingScreenStartButtonTitle	Instruction screen button text color.		string	#FFFFFF
onboardingScreenStartButtonTitleHover	Instruction screen button text hover color.		string	#FFFFFF
onboardingScreenIllumination	Instruction screen "Illumination" icon image.		base64 or url or imported image	``
onboardingScreenAccessories	Instruction screen "No accessories" icon image.		base64 or url or imported image	``
onboardingScreenCameraLevel	Instruction screen "Camera level" icon image.		base64 or url or imported image	``
cameraScreenFrontHintLabelBackground	Camera screen plate with info message background color.	--plate-color	string	#E8E8E8
cameraScreenFrontHintLabelText	Camera screen plate with info message text color.		string	#000000
cameraScreenSectorActive	User progress sector color (available only in the azakaw-liveness component).		string	#7E57C5
cameraScreenSectorTarget	Target sector color (available only in the azakaw-liveness component).	--target-sector-color	string	#BEABE2
cameraScreenStrokeNormal	Stroke color of the camera circle.		string	#7E57C5
cameraScreenStrokeWidth	Stroke width of the camera circle.		number	3
processingScreenProgress	Processing screen spinner color.		string	#7E57C5
retryScreenEnvironmentImage	Retry screen environment image.		base64 or url or imported image	``
retryScreenPersonImage	Retry screen person image.		base64 or url or imported image	``
retryScreenRetryButtonBackground	Retry screen button background color.	--main-color	string	#7E57C5
retryScreenRetryButtonBackgroundHover	Retry screen button background hover color.	--hover-color	string	#7C45B4
retryScreenRetryButtonTitle	Retry screen button text color.		string	#FFFFFF
retryScreenRetryButtonTitleHover	Retry screen button text hover color.		string	#FFFFFF
successScreenImage	Success screen image.		base64 or url or imported image	``