standard

iOS Liveness Detection SDK (v4.1.1) User Guide

Overview

AAILivenessSDK contains the following modules: the core module AAILivenessSDK.xcframework, the UI module AAILivenessUI, the model resource module AAILivenessModel.xcframework, and the dependency modules AAINetwork.xcframework, AAICore.xcframework, AAIDataVisor.xcframework.

The total size of SDK is approximately 6.9MB (arm64, disable bitcode) or 5.5MB (arm64, disable bitcode, without model resource module AAILivenessModel.xcframework).

AAILivenessSDK.xcframework(Dynamic framework, Required module)
This core module provides the main functions of the SDK. The total size of this module is approximately 2.5MB (arm64, disable bitcode). Note that this module only depends on AAINetwork.xcframework, AAICore.xcframework and AAIDataVisor.xcframework.
AAILivenessUI(Source mode, Required module)
This UI module implements the SDK interface and is open source. It contains the default UI logic and related resources. See Customizable UI for information on how to customize the UI.
These resources include images, multi-language files, and audio files. The default UI depends on these resources, during liveness detection, the UI module loads related images and plays audio.
This resource folder is approximately 0.8MB.
AAILivenessModel.xcframework(Dynamic framework, Optional module)
This model resources module contains the model files used by the SDK. This module is optional, if you want to minimize the size of the SDK, you can remove it, and the SDK will automatically download the model files from the server when needed.
The total size of this module is approximately 1.4MB (arm64, disable bitcode).
AAICore.xcframework(Dynamic framework, Required module)
A core library that AAI SDKs depend on. The total size of this module is approximately 0.7MB (arm64, disable bitcode).
AAINetwork.xcframework(Dynamic framework, Required module)
A base network library that AAI SDKs depend on. The total size of this module is approximately 0.8MB (arm64, disable bitcode).
AAIDataVisor.xcframework(Dynamic framework, Required module) A core security library that AAI SDKs depend on. The total size of this module is approximately 0.7MB (arm64, disable bitcode).

SDK requirements and limitations as below:

Minimum iOS version: iOS 10.0
Additional dependent third-party libraries: None
Supported CPU architectures: arm64, x86_64
SDK package size: 6.9MB(arm64, disable bitcode)
Supported bitcode: NO
Supported languages: en, zh-Hans, id, vi, th, es, ms, hi,fil
Use-permissions: NSCameraUsageDescription

Compliance Explanation

See Compliance Explanation for more details.

Migration Guides

If you are upgrading from an older version of the Liveness SDK, please refer to this document to understand the changes.

Run demo project

The demo project is included in the SDK compressed package. Download the AAILivenessSDK and extract it, then navigate to the directory of LivenessSDKSwiftDemo project and install the dependencies:
```
pod install
```
Open xcworkspace file in Xcode.
Specify your market and license content, then start SDK, the license content is obtained by your server calling our openapi.

Installation

CocoaPods (Recommended)

Specify the SDK name and url in the Podfile:


pod 'AAILivenessUI', :http => 'https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-liveness-detection/4.1.1/iOS-Liveness-SDK-V4.1.1.tar.bz2', type: :tbz

pod 'AAILivenessModel', :http => 'https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-libraries/AAILivenessModel/4.0.0/AAILivenessModel-V4.0.0.tar.bz2', type: :tbz

pod 'AAICore', :http => 'https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-libraries/AAICore/1.0.1/AAICore-V1.0.1.tar.bz2', type: :tbz

pod 'AAINetwork', :http => 'https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-libraries/AAINetwork/AAINetwork-V1.0.4.tar.bz2', type: :tbz 

pod 'AAIDataVisorSDK', :http => 'https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-AAIDataVisor-SDK/0.1.5/iOS-AAIDataVisorSDK-V0.1.5.tar.bz2', type: :tbz

Note if you are using static link configuration(that is, you haven't configured use_frameworks! in your Podfile), you need update the pod 'AAILivenessUI' as follows:


pod 'AAILivenessUI', :http => 'https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-liveness-detection/4.1.1/iOS-Liveness-SDK-V4.1.1.tar.bz2', type: :tbz, :modular_headers => true

Run pod install to install the dependencies in your project:

Add camera usage description in Info.plist as bellow. Ignore this step if you have added those.


<key>NSCameraUsageDescription</key>
<string>Use the camera to detect the face movements</string>

Refer to demo project to see how to use the SDK.

Swift package manager

Download the AAILivenessSDK SPM package, then unzip it.
In Xcode, select Project -> Package Dependencies -> Add Local..., then select the AAILivenessUI folder of unzipped folder.

Add camera usage description in Info.plist as bellow. Ignore this step if you have added those.


<key>NSCameraUsageDescription</key>
<string>Use the camera to detect the face movements</string>

Refer the demo project LivenessSDKSwiftDemo_SPM of the unzipped folder to see how to use the SDK.

Carthage

Add the following lines to your Cartfile:


binary "https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-liveness-detection/Carthage/AAILivenessSDK.json" == 4.1.1

binary "https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-liveness-detection/Carthage/AAILivenessUI.json" == 4.1.1

binary "https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-liveness-detection/Carthage/AAILivenessModel.json" == 4.0.0

binary "https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-liveness-detection/Carthage/AAINetwork.json" == 1.0.4

binary "https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-liveness-detection/Carthage/AAICore.json" == 1.0.1

binary "https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-liveness-detection/Carthage/AAIDataVisor.json" == 0.1.5

Run carthage update --platform iOS --use-xcframeworks to download the SDK.
Add the AAILivenessSDK.xcframework, AAILivenessUI.xcframework, AAILivenessModel.xcframework, AAINetwork.xcframework, AAICore.xcframework, AAIDataVisor.xcframework of Carthage/Build folder to the Frameworks, Libraries, and Embedded Content section in the General settings tab of your application targets. Note Embed & Sign should be selected.

Add camera usage description in Info.plist as bellow. Ignore this step if you have added those.


<key>NSCameraUsageDescription</key>
<string>Use the camera to detect the face movements</string>

Download the demo project LivenessSDKSwiftDemo_Carthage to see how to use the SDK.

Manually

Download the AAILivenessSDK, AAILivenessModel, AAINetwork, AAICore, AAIDataVisor then uncompress them and add AAILivenessSDK folder, AAILivenessModel.xcframework, AAINetwork.xcframework, AAICore.xcframework, AAIDataVisor.xcframework to your project:
Choose "TARGETS -> General" add the following system libraries and frameworks in the Frameworks, Libraries, and Embedded Content section:
- libz.tbd
- libc++.tbd
- libresolv.9.tbd
- AVFoundation.framework
- CoreMotion.framework
- SystemConfiguration.framework
- CoreTelephony.framework
- Accelerate.framework
- Metal.framework
- MetalKit.framework
Choose "TARGETS -> General -> Frameworks,Libraries,and Embedded Content", then set AAILivenessSDK.xcframework, AAILivenessModel.xcframework, AAINetwork.xcframework, AAICore.xcframework, AAIDataVisor.xcframework's Embed as "Embed & Sign".
Add -ObjC to the other linker flag in the project configuration.

Add camera usage description in Info.plist as bellow. Ignore this step if you have added those.


<key>NSCameraUsageDescription</key>
<string>Use the camera to detect the face movements</string>

Usage

Below are detailed usage examples for the iOS SDK. We place the iOS SDK sample code inside a button click handler. This is the recommended practice for the iOS SDK, keeping it compact, clear, less prone to missed settings, and helping prevent errors. For available liveness types, see Liveness types.


import UIKit
import AAILivenessUI

public class ViewController: UIViewController {

    public override func viewDidLoad() {
        super.viewDidLoad()
        
        self.addButton("SDK Demo", CGRect(x: 40, y: 140, width: 140, height: 40), #selector(tapSDKBtnAction))
    }
    

    @objc func tapSDKBtnAction() {
        // 1. Specify the market to initialize the SDK
        // If you have subscribed to the Global liveness service,
        // you should pass true to the `isGlobalService` parameter.
        let licenseConfig = AAILDLicenseModeConfig()
        // Set your market
        licenseConfig.market = .indonesia
        // Set whether the SDK is used as a global service
        licenseConfig.isGlobalService = false
        AAILivenessSDK.initWith(licenseConfig)

        // 2. Fetch license then check it
        // Calling our openapi `openapi/face-identity/v1/auth-license` to generate it
        let demoLicenseContent = "your-license-content"
        let checkResult = AAILivenessSDK.configLicenseAndCheck(demoLicenseContent)
        if checkResult == "SUCCESS" {
            // license is valid, show SDK page
            let livenessViewController = AAILivenessViewController()

            // Configure SDK
            let livenessConfig = livenessViewController.livenessConfig
          
            /*
            // 3. Optional: 
            // Configure signatureId
            // Calling our openapi `liveness/ext/v1/generate-signature-id` to generate it.
            // Note this value must be unique per liveness flow.
            // Passing a previously used value will result in a parameter error in SDK.
            livenessConfig.signatureId = "your-signature-id"
            */
            

            /*
            // Optional: 
            // Set liveness type
            livenessConfig.livenessType = "your-liveness-type"
            */
            
            // Other optional configurations ...
            /*
            // Optional:
            // This value can be set in the interval [300, 1000], 
            // the larger the value, the more memory the SDK will consume.
            livenessConfig.resultPictureSize = 600
            */
            
            /*
            // Optional:
            // Set whether to detect face occlusion. The default value is false.
            livenessConfig.detectOcclusion = true
            */

            /*
            // Optional:
            // User binding (strongly recommended).
            // You can use this method to pass your user unique identifier to us,
            // we will establish a mapping relationship based on the identifier.
            // It is helpful for us to check the log when you encountering problems.
            livenessConfig.userId("your-user-id")
            */

            /*
            // Optional:
            // Audit image collection configuration
            let auditImageConfig = AAIAuditImageConfig.default()
            auditImageConfig.imageQuality = 30
            auditImageConfig.enableCollect = true
            auditImageConfig.imageWidth = 300
          
            // Other optional audit image configure item:
            // Try capture a audit image at specific time (the relative time 
            // after the camera is launched). Default is 0(second), means no capture. 
            // auditImageConfig.relativeSecondsCaptureAfterCameraLaunched = 3
          
            livenessConfig.auditImageConfig = auditImageConfig
            */

            /*
            // Optional:
            // Video recording configuration
            // By enabling this feature, the SDK will activate video recording. 
            // After the completion of the liveness process, you can retrieve the video file using
            // SDK methods. The video file format is .mp4. Please note that this video can only be
            // obtained through the SDK and cannot be obtained from the backend. After using the
            // video, it is up to you to decide whether to delete the local file.
            let videoConfig = AAIVideoConfig.default()
            // `.all` means enable the video recording
            // `.unspecified` means disable the video recording
            videoConfig.recordStage = .all
            videoConfig.maxRecordDuration = 60
            livenessConfig.videoConfig = videoConfig
            */

            /*
            // Optional:
            // Set the color of the round border in the avatar preview area. 
            // Default is 0x5B43.
            livenessConfig.normalAvatarBorderColor = .blue
            */
          
            /*
            // Optional:
            // Set the highlight color of the round border in the avatar preview area and
            // the color of the inner ellipse animation line of the 3D mode(near/distant mode)
            // Default is 0x5BC413.
            livenessConfig.highlightAvatarBorderColor = .red
            livenessConfig.innerAnimatedEllipseLineColor = .red
            */

            /*
            // Optional:
            // Set the color of the dashed ellipse line that appears during the 
            // liveness detection. Default is white color.
            // Note this dashed ellipse line only appears during the silent detection
            // stage or motion detection stage.
            livenessConfig.innerEllipseDashedLineColor = .green
            */

            // ...
            // See `AAILivenessConfig.h` for more liveness configuration options 
            // ...
            
            /*
            // Optional:
            // Specify AAILoadingHud brand color. Default is 0x5BC413.
            livenessViewController.hudBrandColor = .red
            */
            
            /*
            // Optional:
            // Specify which language to use for the SDK. The default is nil, 
            // which means the SDK will use the system language.
            // The languages currently supported by sdk are as follows:
            // "en" "id"  "vi"  "zh-Hans"  "th"  "es"  "ms" "hi"
            livenessViewController.language = "id"
            */
          
            /*
            // Optional 
            // Whether to mark the action of tapping back button as "USER_GIVE_UP". 
            // The default is false. If you set true, the `detectionFailureBlk` will be called
            // when the user taps the top left back button while liveneness detection is running.
            livenessViewController.recordUserGiveUp = true
            */

            // ...
            // See `AAILivenessViewController.h` for more page configuration options 
            // ...
            
            // 5. Configure the detection success and failure callbacks
            livenessViewController.detectionSuccessBlk = {(rawVC, result) in
                // Get livenessId
                let livenessId = result.livenessId
                // Get eventId(You should save this ID in case of tracking problems).
                let eventId = result.eventId
                
                let bestImg = result.img
                let bestImgBase64 = result.getImgBase64Str()
                let size = bestImg.size
                print(">>>>>livenessId: \(livenessId), imgSize: \(size.width), \(size.height)")
                // Do something... 
                // (e.g., call liveness-detection api to get liveness-score)
                /*
                // Get video record result
                if let videoRecordResult = result.syncGetVideoRecordResult {
                   if videoRecordResult.code != .failed {
                        print("Video path is : \(videoRecordResult.videoPath ?? "")")
                    }
                }
                */
                rawVC.navigationController?.popViewController(animated: true)
            }

            livenessViewController.detectionFailureBlk = {(rawVC, result) in
                // Get eventId(You should save this ID in case of tracking problems).
                let eventId = result.eventId
                print("Detection failed: \(result.errorCode), message: \(result.errorMsg), transactionId: \(result.transactionId), eventId: \(eventId)")
                /*
                // Get video record result
                if let videoRecordResult = result.syncGetVideoRecordResult {
                   if videoRecordResult.code != .failed {
                        print("Video path is : \(videoRecordResult.videoPath ?? "")")
                    }
                }
                */
                
                /*
                // If you want to retry, please call method 'rawVC.restartDetection()'.
                // Note: If you passed a `signatureId` to the `livenessConfig`, 
                // you must update it before retrying,otherwise, you will get a `PARAMETER_ERROR`.
                // 
                // For example:
                let livenessConfig = rawVC.livenessConfig
                // Update signatureId
                livenessConfig.signatureId = "your-new-signature-id"
                // Begin retry
                rawVC.restartDetection()
                */

                rawVC.navigationController?.popViewController(animated: true)
            }

            // 6. Show the liveness detection page(push or present)
            self.navigationController?.pushViewController(livenessViewController, animated: true)
        } else if checkResult == "LICENSE_EXPIRE" {
            print("LICENSE_EXPIRE: please call your server's api to generate a new license")
        } else if checkResult == "APPLICATION_ID_NOT_MATCH" {
            print("APPLICATION_ID_NOT_MATCH: please bind your app's bundle identifier on our cms website, then recall your server's api to generate a new license")
        } else {
            // other unkown errors ...
            /*
            ERROR_LICENSE(1): The license was parsed successfully, but necessary authentication information is missing. This case generally should not occur. 
            ERROR_LICENSE(2): The license was parsed successfully, but the internal format is incorrect. This case generally should not occur.
            ERROR_LICENSE(3): The license was parsed successfully, but it is an incompatible license, such as using an IQA license for liveness detection.
            ERROR_LICENSE(4，5): The license parsing failed. Please check if the license contains mismatched quotes, carriage returns, etc.
            */
            print("\(checkResult)")
        }
    } // end tapSDKBtnAction()
    
} // end ViewController

Error code

See error code for all possible values of errorCode in AAILivenessFailureResult.

FAQ

See FAQ

Change logs and release history

See iOS liveness SDK release history