Getting Started

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

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.

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.

1. Add the Required Permissions

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

Response

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

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

Response

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

Sandbox Environment

Response

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

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

Response

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

3. Add your Activation Key

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

Response

<key>vida_activation_key</key>
<string>__activation_key_provided_by_vida__</string>

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.

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.

Response

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
    )

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.

vidaLiveness.startDetection()

Release

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

vidaLiveness.release()

Compatibility

The vidaLiveness iOS framework is compatible with iOS v13 and above, only on physical devices.

Configuration Reference

VIDALivenessRequest

Defines the configuration for the liveness request.

Property	Type	Required	Description
apiKey	String	Required	API key provided by VIDA.
licenseKey	String	Required	License key provided by VIDA.
eKYCID	String	Optional	ID for the user's eKYC for which the liveness is to be done.
userId	String	(Optional) if ID Fraud Shield Enabled	UserId to be tracked in idFraudShield. If you do not provide one, the SDK uses a default value. Recommended when idFraudShield is enabled for the flow, so fraud rules can be applied per user.

SDKUIComponentConfig

The SDKUIComponentConfig helps in configuring the UI. The detailed guide on configuration is available in UI Customization through API section.

VIDAFaceDetectionOptions

Configuration options for the liveness detection.

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.

onSuccess(response: VIDALivenessResponse)

onError

Invoked when an error occurs during the liveness flow.

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

Parameter	Description
errorCode	An integer representing the error code.
errorMessage	A string message detailing the error.
response	Final frame of the liveness flow, applicable scores, and error details (if available).

VIDALivenessResponse

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

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