> For the complete documentation index, see [llms.txt](https://docs.vida.id/identity-stack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vida.id/identity-stack/verify/liveness/integration/liveness-sdk/ios-sdk/customization/customization-through-api.md).

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

{% hint style="info" %}
**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.
{% endhint %}

## UI Customization Options

### Tutorial Screen

<figure><img src="/files/zR5esBf7CGdDDWrJwtFb" alt="" width="563"><figcaption></figcaption></figure>

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

<table><thead><tr><th width="280.77734375">Property</th><th width="105.56640625">Type</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td><code>tutorialScrBackgroundColor</code></td><td>UIColor</td><td>White</td><td>Background color of the tutorial screen.</td></tr><tr><td><code>tutorialScrTextColor</code></td><td>UIColor</td><td>Black</td><td>Text color of the tutorial screen.</td></tr><tr><td><code>tutorialInstructionTextColor</code></td><td>UIColor</td><td>Black</td><td>Text color of the on-screen instruction. </td></tr><tr><td><code>tutorialWarningTextColor</code></td><td>UIColor</td><td>Black</td><td>Text color of the warning message.</td></tr><tr><td><code>tutorialWarningIconTextColor</code></td><td>UIColor</td><td>rgb(0.49, 0.51, 0.53)</td><td>Text color of the warning icon labels.</td></tr><tr><td><code>transactionIdBackgroundColor</code></td><td>UIColor</td><td>rgb(0.95, 0.95, 0.95)</td><td>Background color of the transaction ID label.</td></tr><tr><td><code>transactionIdTextColor</code></td><td>UIColor</td><td>rgb(0.51, 0.51, 0.51)</td><td>Text color of the transaction ID label.</td></tr></tbody></table>

### Camera Permission Screen

<figure><img src="/files/vpP1HylAbTlNg3DYt8Fx" alt="" width="563"><figcaption></figcaption></figure>

The screen that requests camera permission from the user.

<table><thead><tr><th width="280.77734375">Property</th><th width="105.56640625">Type</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td><code>cameraPermissionTitleText</code></td><td>String</td><td>-</td><td>Title text of the camera permission screen.</td></tr><tr><td><code>cameraPermissionDescriptionText</code></td><td>String</td><td>-</td><td>Description text on the camera permission screen.</td></tr><tr><td><code>cameraPermissionScrBackgroundColor</code></td><td>UIColor</td><td>Black</td><td>Background color of the camera permission screen.</td></tr><tr><td><code>cameraPermissionScrTextColor</code></td><td>UIColor</td><td>Black</td><td>Text color of the camera permission screen.</td></tr></tbody></table>

{% hint style="info" %}
**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.
{% endhint %}

### Camera Preview Screen

<figure><img src="/files/vKVxaL5blRVRFl3COkV2" alt="" width="563"><figcaption></figcaption></figure>

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

<table><thead><tr><th width="293">Property</th><th width="105.56640625">Type</th><th width="120.98828125">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>cameraPreviewScrBackgroundColor</code></td><td>UIColor</td><td>White</td><td>Background color of the camera preview screen.</td></tr><tr><td><code>overlayBackgroundColor</code></td><td>UIColor</td><td>Black, 70% opacity</td><td>Background color of the camera overlay.</td></tr><tr><td><code>overlayBorderColor</code></td><td>UIColor</td><td>White</td><td>Border color of the camera overlay.</td></tr><tr><td><code>overlayBorderWidth</code></td><td>CGFloat</td><td>10</td><td>Border width of the camera overlay.</td></tr><tr><td><code>overlayShape</code></td><td>OverlayShape</td><td><code>.oval</code></td><td>Shape of the camera overlay (see Overlay shape below).</td></tr></tbody></table>

### Camera Capture Screen (messaging)

The messages and animation stroke shown during face capture.

<table><thead><tr><th width="246.23828125">Property</th><th width="105.56640625">Type</th><th width="120.98828125">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>strokeBorderColor</code></td><td>UIColor</td><td>rgb(0.03, 1, 0.72)</td><td><p>Stroke border color for elements on the camera capture screen</p><p>(the animation stroke).</p></td></tr><tr><td><code>cameraMessageTextColor</code></td><td>UIColor</td><td>Black</td><td>Text color for messages on the camera capture screen.</td></tr><tr><td><code>cameraMessageFont</code></td><td>UIFont</td><td>HelveticaNeue-Bold, 16</td><td>Font for messages on the camera capture screen.</td></tr></tbody></table>

### Review Screen

<figure><img src="/files/2CWvzL3ce0DoSwwdVI9g" alt="" width="563"><figcaption></figcaption></figure>

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

<table><thead><tr><th width="246.23828125">Property</th><th width="105.56640625">Type</th><th width="120.98828125">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>reviewScreenBackgroundColor</code></td><td>UIColor</td><td>White</td><td>Background color of the review screen.</td></tr><tr><td><code>reviewScreenTextColor</code></td><td>UIColor</td><td>Black</td><td>Text color of the review screen.</td></tr><tr><td><code>reviewInstructionTextColor</code></td><td>UIColor</td><td>rgb(0.617, 0.633, 0.667)</td><td>Instruction text color on the review screen.</td></tr><tr><td><code>reviewInstructionFont</code></td><td>UIFont</td><td>HelveticaNeue, 15</td><td>Instruction font on the review screen.</td></tr></tbody></table>

### Call-to-Action buttons

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

{% code expandable="true" %}

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

{% endcode %}

<table><thead><tr><th width="211.67578125">Property</th><th width="113.3671875">Type</th><th width="192.3125">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>primaryCTAConfig</code></td><td>CTAConfig</td><td>bg rgb(0.35, 0.74, 0.95), white text, HelveticaNeue-Bold 15</td><td>Primary call-to-action button.</td></tr><tr><td><code>secondaryCTAConfig</code></td><td>CTAConfig</td><td>bg rgb(0.95, 0.95, 0.95), black text, HelveticaNeue 15</td><td>Secondary call-to-action button.</td></tr></tbody></table>

### Overlay shape

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

<table><thead><tr><th width="247.24609375">Value</th><th>Shape</th></tr></thead><tbody><tr><td><code>.oval</code></td><td>Oval overlay (default).</td></tr><tr><td><code>.circle</code></td><td>Circular overlay.</td></tr><tr><td><code>.square</code></td><td>Square overlay.</td></tr><tr><td><code>.rectangle</code></td><td>Rectangular overlay.</td></tr></tbody></table>

### Other options

<table><thead><tr><th width="211.67578125">Property</th><th width="113.3671875">Type</th><th width="192.3125">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>maxRetryAttempts</code></td><td>Int</td><td>2</td><td>Maximum number of retry attempts allowed.</td></tr></tbody></table>

## Full Initializer Reference

The complete `SDKUIComponentConfig` initializer with all default values:

<details>

<summary>Response</summary>

```swift
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
)
```

</details>

## Active Liveness

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

{% hint style="info" %}
**Requirement**

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

### Enable active liveness

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

```swift
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

<table><thead><tr><th width="259.18359375">Gesture</th><th>Description</th></tr></thead><tbody><tr><td><code>.zoomFace</code></td><td>Enables the zoom gesture.</td></tr><tr><td><code>.blinkEyes</code></td><td>Blink gesture.</td></tr><tr><td><code>.smile</code></td><td>Smile gesture.</td></tr><tr><td><code>.shakeHead</code></td><td>Shake-head gesture.</td></tr></tbody></table>

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

{% hint style="info" %}
**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` .
{% endhint %}

### Apply the Configuration

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

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