Customization through API

The SDKUIComponentConfig struct lets you adapt the UI of the full liveness flow to match your app's branding — screen background colors, text colors, fonts, and camera overlay styling. This page lists every option by screen, then covers how to enable active liveness gestures.

How to apply customizations

Create an SDKUIComponentConfig instance, overriding only the options you want to change (every option has a default), and pass it to vidaLiveness.initialize(...) through the sdkUIComponentConfig parameter.

UI Customization Options

Tutorial Screen

The initial tutorial screen shown before capture, including the transaction ID label, instructions, and "avoid wearing these" warning.

Property	Type	Default	Description
tutorialScrBackgroundColor	UIColor	White	Background color of the tutorial screen.
tutorialScrTextColor	UIColor	Black	Text color of the tutorial screen.
tutorialInstructionTextColor	UIColor	Black	Text color of the on-screen instruction.
tutorialWarningTextColor	UIColor	Black	Text color of the warning message.
tutorialWarningIconTextColor	UIColor	rgb(0.49, 0.51, 0.53)	Text color of the warning icon labels.
transactionIdBackgroundColor	UIColor	rgb(0.95, 0.95, 0.95)	Background color of the transaction ID label.
transactionIdTextColor	UIColor	rgb(0.51, 0.51, 0.51)	Text color of the transaction ID label.

Camera Permission Screen

The screen that requests camera permission from the user.

Property	Type	Default	Description
cameraPermissionTitleText	String	-	Title text of the camera permission screen.
cameraPermissionDescriptionText	String	-	Description text on the camera permission screen.
cameraPermissionScrBackgroundColor	UIColor	Black	Background color of the camera permission screen.
cameraPermissionScrTextColor	UIColor	Black	Text color of the camera permission screen.

Note: cameraPermissionTitleText and cameraPermissionDescriptionText are documented as options but do not appear in the initializer signature in the source. Confirm how they are set before relying on them.

Camera Preview Screen

The live camera preview, including the face overlay and its border.

Property	Type	Default	Description
cameraPreviewScrBackgroundColor	UIColor	White	Background color of the camera preview screen.
overlayBackgroundColor	UIColor	Black, 70% opacity	Background color of the camera overlay.
overlayBorderColor	UIColor	White	Border color of the camera overlay.
overlayBorderWidth	CGFloat	10	Border width of the camera overlay.
overlayShape	OverlayShape	.oval	Shape of the camera overlay (see Overlay shape below).

Camera Capture Screen (messaging)

The messages and animation stroke shown during face capture.

Property	Type	Default	Description
strokeBorderColor	UIColor	rgb(0.03, 1, 0.72)	Stroke border color for elements on the camera capture screen (the animation stroke).
cameraMessageTextColor	UIColor	Black	Text color for messages on the camera capture screen.
cameraMessageFont	UIFont	HelveticaNeue-Bold, 16	Font for messages on the camera capture screen.

Review Screen

The screen that lets the user review the captured photo before submitting.

Property	Type	Default	Description
reviewScreenBackgroundColor	UIColor	White	Background color of the review screen.
reviewScreenTextColor	UIColor	Black	Text color of the review screen.
reviewInstructionTextColor	UIColor	rgb(0.617, 0.633, 0.667)	Instruction text color on the review screen.
reviewInstructionFont	UIFont	HelveticaNeue, 15	Instruction font on the review screen.

Call-to-Action buttons

Configure the primary and secondary CTA buttons used across the whole liveness flow. Each takes a CTAConfig:

init(backgroundColor: UIColor, textColor: UIColor, textFont: UIFont?)

Property	Type	Default	Description
primaryCTAConfig	CTAConfig	bg rgb(0.35, 0.74, 0.95), white text, HelveticaNeue-Bold 15	Primary call-to-action button.
secondaryCTAConfig	CTAConfig	bg rgb(0.95, 0.95, 0.95), black text, HelveticaNeue 15	Secondary call-to-action button.

Overlay shape

Set the shape of the camera overlay with the overlayShape option (default .oval). Available shapes:

Value	Shape
.oval	Oval overlay (default).
.circle	Circular overlay.
.square	Square overlay.
.rectangle	Rectangular overlay.

Other options

Property	Type	Default	Description
maxRetryAttempts	Int	2	Maximum number of retry attempts allowed.

Full Initializer Reference

The complete SDKUIComponentConfig initializer with all default values:

Response

init(
        tutorialScrBackgroundColor: UIColor = UIColor.white,
        tutorialScrTextColor: UIColor = UIColor.black,
        transactionIdBackgroundColor: UIColor = UIColor(red: 0.95, green: 0.95, blue: 0.95, alpha: 1),
        transactionIdTextColor: UIColor = UIColor(red: 0.51, green: 0.51, blue: 0.51, alpha: 1),
        tutorialWarningTextColor: UIColor = UIColor.black,
        tutorialWarningIconTextColor: UIColor = UIColor(red: 0.49, green: 0.51, blue: 0.53, alpha: 1),
        tutorialInstructionTextColor: UIColor = UIColor.black,
        cameraPermissionScrBackgroundColor: UIColor = UIColor.white,
        cameraPermissionScrTextColor: UIColor = UIColor.black,
        primaryCTAConfig: CTAConfig = CTAConfig(
            backgroundColor: UIColor(red: 0.35, green: 0.74, blue: 0.95, alpha: 1),
            textColor: UIColor.white,
            textFont: UIFont(name: "HelveticaNeue-Bold", size: 15.0)
        ),
        secondaryCTAConfig: CTAConfig = CTAConfig(
            backgroundColor: UIColor(red: 0.95, green: 0.95, blue: 0.95, alpha: 1),
            textColor: UIColor.black,
            textFont: UIFont(name: "HelveticaNeue", size: 15.0)
        ),
        cameraPreviewScrBackgroundColor: UIColor = UIColor.white,
        overlayShape: OverlayShape = .oval,
        overlayBackgroundColor: UIColor = UIColor(white: 0, alpha: 0.7),
        overlayBorderColor: UIColor = UIColor.white,
        overlayBorderWidth: CGFloat = 10,
        strokeBorderColor: UIColor = UIColor(red: 0.03, green: 1, blue: 0.72, alpha: 1),
        cameraMessageTextColor: UIColor = UIColor.black,
        cameraMessageFont: UIFont? = UIFont(name: "HelveticaNeue-Bold", size: 16.0),
        reviewScreenBackgroundColor: UIColor = UIColor.white,
        reviewScreenTextColor: UIColor = UIColor.black,
        reviewInstructionTextColor: UIColor = UIColor(
            red: 0.617,
            green: 0.633,
            blue: 0.667,
            alpha: 1
        ),
        reviewInstructionFont: UIFont? = UIFont(name: "HelveticaNeue", size: 15.0),
        maxRetryAttempts: Int = 2
)

Active Liveness

By default, active liveness is not enabled. You can enable gesture-based active liveness (Blink, Smile, Shake) by updating your detectionOptions configuration.

Requirement

Use iOS build version 1.4.35 or later to add the Blink / Smile / Shake configuration.

Enable active liveness

Update VIDAFaceDetectionOptions to turn on active liveness and provide the list of allowed gestures:

private var detectionOptions: VIDAFaceDetectionOptions = VIDAFaceDetectionOptions(
    // Existing configuration
    enableActiveLiveness: true, // default is false if not passed
    allowedGestures: Set([.blinkEyes, .smile, .shakeHead]) // default is set to allowedGestures: Set([.zoomFace]), in case of enableActiveLiveness is true
)

Allowed gestures

Gesture	Description
.zoomFace	Enables the zoom gesture.
.blinkEyes	Blink gesture.
.smile	Smile gesture.
.shakeHead	Shake-head gesture.

.blinkEyes , .smile , and .shakeHead can be configured individually or in combination. If active liveness is enabled and allowedGestures is not passed, the default gesture is .zoomFace.

Don't mix gesture sets

Use either .zoomFace or any combination of .blinkEyes / .smile / .shakeHead. Combining gestures from both sets results in an exception with error code 70011 .

Apply the Configuration

Pass the updated sdkUIComponentConfig and detectionOptions into the vidaLiveness.initialize call:

private func initializeVIDALiveness() {
    // Existing configuration
    vidaLiveness.initialize(
        // Existing configuration
        sdkUIComponentConfig: sdkUIComponentConfig,
        detectionOptions: detectionOptions,
        // Existing configuration
    )
}