> 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/getting-started.md).

# Getting Started

This guide walks through integrating the `vidaLiveness` iOS framework — from prerequisites and installation through initialization, running the liveness flow, and handling results.

{% hint style="info" %}
**Before you begin: Get your Activation Key**

You need an Activation Key to access the VIDA SDK. If you don't have one yet, reach out to the [**VIDA support team**](mailto:support@vida.id).

**Using ID Fraud Shield?**

When ID Fraud Shield is enabled for your account, it runs alongside this liveness flow to strengthen verification with additional fraud-risk signals. Add the ID Fraud Shield pod (Step 2), and pass a `userId` in the liveness request so fraud rules can be applied per user.

The `userId` is **optional from Liveness SDK `v1.9.4+`** — if you do not provide one, the SDK uses a default value — but we recommend setting your own so fraud rules can be applied per user.

On versions earlier than `v1.9.4`, the `userId` is **required** when ID Fraud Shield is enabled. Not setting it will result in an error.
{% endhint %}

## 1. Add the Required Permissions

To access camera features, add the following key to your app's `Info.plist` file:

<details>

<summary>Response</summary>

{% code expandable="true" %}

```xml
<key>NSCameraUsageDescription</key>
<string>Description of why your app needs camera access</string>
```

{% endcode %}

</details>

## 2. Add the SDK Dependency

Integrate `vidaLiveness` using CocoaPods. Add the `VidaLiveness` pod for your target environment. If ID Fraud Shield is enabled for your account, also add the `idFraudShield`\
pod.

#### Production Environment

<details>

<summary>Response</summary>

{% code expandable="true" %}

```ruby
# Production Environment
source 'https://bitbucket.org/vidaid/ios-sdk.git'

pod 'VidaLiveness', podspec:
'https://sdk-repo.vida.id/ios/vidaLiveness/X.Y.Z.podspec'

# If the ID Fraud Shield check is Enabled
pod 'idFraudShield', 'x.y.z' or 'x.y.z-Sandbox'

## X.Y.Z is the version of the framework that you want to use.
```

{% endcode %}

</details>

#### Sandbox Environment

<details>

<summary>Response</summary>

{% code expandable="true" %}

```ruby
#Sandbox Environment
source 'https://bitbucket.org/vidaid/ios-sdk.git'

pod 'VidaLiveness', podspec:
'https://sdk-repo.dev.vida.id/ios/vidaLiveness/X.Y.Z-Sandbox.podspec'

#If the ID Fraud Shield check is Enabled
pod 'idFraudShield', 'X.Y.Z-Sandbox'

X.Y.Z is the version of the framework that you want to use.
```

{% endcode %}

</details>

Then add the following `post_install` hook to your `Podfile` so the pods are built for distribution (enables Swift module stability):

<details>

<summary>Response</summary>

{% code expandable="true" %}

```swift
post_install do |installer|
    installer.pods_project.targets.each do |target|
        target.build_configurations.each do |config|
            config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        end
    end
end
```

{% endcode %}

</details>

## 3. Add your Activation Key

In your application's `Info.plist` file, provide the activation key provided by VIDA:

<details>

<summary>Response</summary>

{% code expandable="true" %}

```xml
<key>vida_activation_key</key>
<string>__activation_key_provided_by_vida__</string>
```

{% endcode %}

</details>

## 4. Initialize the Framework

In your `UIViewController` subclass, import `vidaLiveness` , create an instance of `VIDALiveness` , and call the initialize API to set up the framework.&#x20;

The `initialize` API takes a `VIDALivenessRequest` , an `SDKUIComponentConfig` , detection options, flags for showing the tutorial and review screens, a language code, a delegate\
for receiving updates, and a navigation controller for presenting UI components.

<details>

<summary>Response</summary>

{% code expandable="true" %}

```swift
import vidaLiveness

let vidaLiveness = VIDALiveness()

vidaLiveness.initialize(
        vidaLivenessRequest: yourLivenessRequest,
        sdkUIComponentConfig: yourSDKUIComponentConfig,
        detectionOptions: yourDetectionOptions,
        shouldShowTutorialFlow: true, // Set to true if you want to show the tutorial screen
        shouldShowReviewScreen: true // Set to true if you want to show the review screen
        languageCode: yourLanguageString, //ISO-639-1 code for the language
        delegate: yourDelegate,
        presentNavigationController: yourNavigationController
    )
```

{% endcode %}

</details>

## 5. Run the Liveness Flow

#### Start detection

Once the framework is initialized, call `startDetection()` to activate the camera and guide the user through the liveness check.

{% code expandable="true" %}

```swift
vidaLiveness.startDetection()
```

{% endcode %}

#### Release

After the user completes the check, call `release()` to free up resources.

```swift
vidaLiveness.release()
```

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

The `vidaLiveness` iOS framework is compatible with **iOS v13 and above**, only on physical devices.
{% endhint %}

## Configuration Reference

#### VIDALivenessRequest

Defines the configuration for the liveness request.

<table><thead><tr><th width="135.3671875">Property</th><th width="104.99609375">Type</th><th width="149.1640625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>apiKey</code></td><td>String</td><td>Required</td><td>API key provided by VIDA.</td></tr><tr><td><code>licenseKey</code></td><td>String</td><td>Required</td><td>License key provided by VIDA.</td></tr><tr><td><code>eKYCID</code></td><td>String</td><td>Optional</td><td>ID for the user's eKYC for which the liveness is to be done.</td></tr><tr><td><code>userId</code></td><td>String</td><td>(Optional) if ID Fraud Shield Enabled</td><td>UserId to be tracked in <code>idFraudShield</code>. If you do not provide one, the SDK uses a default value. Recommended when <code>idFraudShield</code> is enabled for the flow, so fraud rules can be applied per user.</td></tr></tbody></table>

#### SDKUIComponentConfig

The `SDKUIComponentConfig` helps in configuring the UI. The detailed guide on configuration is available in [UI Customization through API](/identity-stack/verify/liveness/integration/liveness-sdk/ios-sdk/customization/customization-through-api.md) section.

#### VIDAFaceDetectionOptions

Configuration options for the liveness detection.

```swift
init(detectionTimeout: Int, minimumStableFrame: Int, eyeOpenProbability: Float)
```

## Handling Results - The VIDALivenessProtocol

The `VIDALivenessProtocol` manages the lifecycle and events of the liveness flow and returns values via the delegate.

### onInitialized()

Called when `VIDALiveness` has been successfully initialized after `initialize(vidaLivenessRequest:sdkUIComponentConfig:detectionOptions:shouldShowTutorialFlow:delegate:presentNavigationController:)` is called. Any subsequent liveness API calls should be made only after this method is triggered.

### onSuccess

Triggered upon successful completion of the liveness flow. The `response` contains the final frame of the liveness flow and various scores, as applicable.&#x20;

```swift
onSuccess(response: VIDALivenessResponse)
```

### onError&#x20;

Invoked when an error occurs during the liveness flow.

```swift
onError (errorCode: Int, errorMessage: String, response: VIDALivenessResponse)
```

<table><thead><tr><th width="182.6015625">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>errorCode</td><td>An integer representing the error code.</td></tr><tr><td>errorMessage</td><td>A string message detailing the error.</td></tr><tr><td>response</td><td>Final frame of the liveness flow, applicable scores, and error details (if available).</td></tr></tbody></table>

### VIDALivenessResponse

Returned on successful completion of the liveness flow. Contains the final frame and the scores below.

<table><thead><tr><th width="190.609375">Property</th><th width="119.4296875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>imageData</code></td><td>Data</td><td>Final frame captured after liveness completes. Returned as null in case of errors.</td></tr><tr><td><code>livenessScore</code></td><td>Double</td><td>Likelihood the image is of a live person, in the range 0 to 1. A default of -1 is sent if not applicable.</td></tr><tr><td><code>manipulationScore</code></td><td>Double</td><td>Likelihood the image has been manipulated or altered, in the range 0 to 1. A default of -1 is sent if not applicable.</td></tr><tr><td><code>errorDetails</code></td><td>String</td><td>Details about any error that occurred, or null if no error occurred.</td></tr><tr><td><code>transactionId</code></td><td>String</td><td>Transaction ID of the liveness detection event.</td></tr></tbody></table>