Documentation

Migration Guides

Overview

From 4.0.0, we've introduced significant API improvements and feature enhancements. To make upgrading easier, here’s what you need to know:

  • AAILivenessResult has been renamed to AAILivenessSuccessResult
  • AAILivenessFailedResult has been renamed to AAILivenessFailureResult
  • AAIAdditionalConfig has been renamed to AAILivenessConfig
  • All audit image settings have been moved from AAIAdditionalConfig to the AAIAuditConfig class
  • If using staticKey or ticket for initialization, refer to this FAQ resource for code migration guidance.

Before & After Example

Before 4.0.0, we may using SDK like this:

(Note: Only partial configuration examples are shown here due to the SDK's extensive options)

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))
       
        // Init SDK
        AAILivenessSDK.initWith(.indonesia)

        // Configure SDK
        /*
        AAILivenessSDK.configResultPictureSize(600)
        */
        
        /*
        // Set whether to detect face occlusion. The default value is false.
        AAILivenessSDK.configDetectOcclusion(true)
        */
        
        /*
        // 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.
        AAILivenessSDK.configUserId("your-user-id")
        */
        
        let additionalConfig = AAILivenessSDK.additionalConfig()
        
        /*
        // Set signature ID for the liveness detection.
        additionalConfig.signatureId = "your-signature-id"
        */
        
        /*
        // Audit image collection configuration
        additionalConfig.enableCollectAuditImages = true
        additionalConfig.auditImageWidth = 300
        additionalConfig.auditImageQuality = 30
        // ... Other audit image configurations
        */
        
        /*
        // Video recording configuration
        let videoConfig = AAIVideoConfig.default()
        videoConfig.recordStage = .prepareAndMotion
        videoConfig.maxRecordDuration = 60
        AAILivenessSDK.configVideo(videoConfig)
        */
        
        /*
        // Set the color of the round border in the avatar preview area. Default is clear color.
        additionalConfig.roundBorderColor = UIColor(red: 0.36, green: 0.768, blue: 0.078, alpha: 1)
        */
        
        /*
        // Set the color of the ellipse dashed line that appears during the liveness detection. Default is white color.
        additionalConfig.ellipseLineColor = .green
        */
        
        // ... Other additional configurations
        
        
    }
    
    @objc func tapSDKBtnAction() {
       let demoLicenseContent = "your-license-content"
       let checkResult = AAILivenessSDK.configLicenseAndCheck(demoLicenseContent)
        if checkResult == "SUCCESS" {
            // license is valid, show SDK page
            let livenessViewController = AAILivenessViewController()
            // other configurations can be set here
            // ...
            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)")
                /*
                // Get video record result
                let videoConfig = AAILivenessSDK.videoConfig()
                if let videoConfig = videoConfig, videoConfig.recordStage != .unspecified {
                    if let videoResult = AAILivenessSDK.syncGetLatestVideoRecordResult() {
                        if videoResult.code != .failed {
                            print("Video path is : \(videoResult.videoPath ?? "")")
                        }
                    }
                }
                */
                // Do something... (e.g., call anti-spoofing api to get score)
                
                rawVC.navigationController?.popViewController(animated: true)
            }
            livenessViewController.detectionFailedBlk = {(rawVC, errorInfo) in
                let result = AAILivenessFailedResult(errorInfo: errorInfo)
                // 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
                let videoConfig = AAILivenessSDK.videoConfig()
                if let videoConfig = videoConfig, videoConfig.recordStage != .unspecified {
                    if let videoResult = AAILivenessSDK.syncGetLatestVideoRecordResult() {
                        if videoResult.code != .failed {
                            print("Video path is : \(videoResult.videoPath ?? "")")
                        }
                    }
                }
                */
                rawVC.navigationController?.popViewController(animated: true)
            }
            self.navigationController?.pushViewController(livenessViewController, animated: true)
        }
    }
    
}
 

From 4.0.0, we should using SDK like this:

(Note: Only partial configuration examples are shown here due to the SDK's extensive options)

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() {
         // Init SDK
        AAILivenessSDK.initWith(.indonesia)
        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

            /*
            livenessConfig.resultPicutreSize = 600
            */

            /*
            // Set whether to detect face occlusion. The default value is false.
            livenessConfig.detectOcculsion = true
            */

            /*
            // 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")
            */

            /*
            // Set signature ID for the liveness detection.
            livenessConfig.signatureId = "your-signature-id"
            */

            /*
            // Audit image collection configuration
            let auditImageConfig = AAIAuditImageConfig.default()
            auditImageConfig.imageQuality = 30
            auditImageConfig.enableCollect = true
            auditImageConfig.imageWidth = 300
            // ... Other audit image configurations
            livenessConfig.auditImageConfig = auditImageConfig
            */

            /*
            // Video recording configuration
            let videoConfig = AAIVideoConfig.default()
            videoConfig.recordStage = .all
            videoConfig.maxRecordDuration = 60
            livenessConfig.videoConfig = videoConfig
            */

            /*
            // Set the color of the round border in the avatar preview area. Default is clear color.
            livenessConfig.normalAvatarBorderColor = UIColor(red: 0.36, green: 0.768, blue: 0.078, alpha: 1)
            */
        
            /*
            // Set the color of the ellipse dashed line that appears during the liveness detection. Default is white color.
            livenessConfig.innerEllipseDashedLineColor = .green
            */

            // ... Other livenessConfig configurations
            // ... Other livenessViewController configurations

            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 anti-spoofing api to get score)
                /*
                // Get video record result
                if let videoRecordResult = result.syncGetVideoRecordResult {
                   if videoResult.code != .failed {
                        print("Video path is : \(videoResult.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 videoResult.code != .failed {
                        print("Video path is : \(videoResult.videoPath ?? "")")
                    }
                }
                */
                rawVC.navigationController?.popViewController(animated: true)
            }
            self.navigationController?.pushViewController(vc, 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 {
            print("\(checkResult)")
        }
    }
    
}

Detail API List

APIs in the table below are now unavailable or deprecated since 4.0.0. You’ll need to update your code accordingly.
Here we explain some document properties upfront to help you understand the table.

  • livenessConfig is an instance of AAILivenessConfig and a property of AAILivenessViewController
  • auditImageConfig is an instance of AAIAuditImageConfigand a property of AAILivenessConfig
  • livenessSuccessResult is an instance of classAAILivenessSuccessResult
  • livenessFailureResult is an instance of class AAILivenessFailureResult
  • livenessViewController is an instance of class AAILivenessViewController

errorCode change detail

The following is a detailed list of changed or newly added error codes. Note that this list only includes modified/new errorCode entries. Codes not listed remain unchanged. For a complete reference of all error codes, please consultthis documentation.

old errorCodenew errorCodeNotes

MUTI_FACE

MULTIPLE_FACE

renamed

PREPARE_TIMEOUT

ACTION_TIMEOUT

If you want to pinpoint which stage caused the timeout, check livenessVC.livenessStage. For example:

If the value is AAILivenessStageSilent, it means the timeout occurred during the silent stage.

If it’s AAILivenessStageAuth, the timeout happened during the Auth request stage, etc.

NO_RESPONSE

AUTH_NETWORK_{errorCode} or UPLOAD_IMAGE_DATA_NETWORK_ERROR_{errorCode}

AUTH_NETWORK_ERROR_{errorCode}: Indicates a network error occurred during the Auth request stage. For example, AUTH_NETWORK_ERROR_-1001 means the network request timed out during authorization.

UPLOAD_IMAGE_DATA_NETWORK_ERROR_{errorCode}: Indicates a network error occurred during the image data upload stage. For example, UPLOAD_IMAGE_DATA_NETWORK_ERROR_-1001 means the network request timed out while uploading image data.

    AUTH_GIVE_UP

      UPLOAD_IMAGE_DATA_GIVE_UP

        CAMERA_OPEN_FAILED

        Camera open failed, please try again

          ERROR_NO_PARAM

          No available model parameters matched

            MODEL_ERROR

            This means that the model file is corrupted or load failed


            AAILivenessViewController

            Method/PropertyVersion RangestatusAlternativeNotes

            detectPhonePortraitDirection

            >=1.2.3 <4.0.0

            unavailable

              detectionActions

              >=1.2.3 <4.0.0

              unavailable

              livenessConfig.livenessType

              prepareTimeoutInterval

              >=1.2.9 <4.0.0

              unavailable

              livenessConfig.silentTimeout

              actionTimeoutInterval

              >=1.2.8 <4.0.0

              unavailable

              livenessConfig.actionTimeout

              timeoutDurationOf3DMode

              >=3.0.4 <4.0.0

              unavailable

              livenessConfig.distantCloseTimeout

              cameraPermissionDeniedBlk

              >=1.2.3 <4.0.0

              unavailable

              detectionFailureBlk

              Behavior change since 4.0.0:
              When camera access is denied by the user, the SDK now triggers the detectionFailureBlk callback.

              detectionReadyBlk

              >=1.2.3 <4.0.0

              unavailable

                frameDetectedBlk

                >=1.2.3 <4.0.0

                unavailable

                  detectionTypeChangedBlk

                  >=1.2.3 <4.0.0

                  unavailable

                  livenessStageChangedBlk

                  Behavior change since 4.0.0:
                  AAIDetectionType is unavailable and replaced by AAILivenessStage

                  detectionFailedBlk

                  >=1.2.3 <4.0.0

                  unavailable

                  detectionFailureBlk

                  - (void)showImgWithType:(AAIDetectionType)detectionType

                  >=1.2.3 <4.0.0

                  unavailable

                  - (void)updateImgWhenStageChange:(AAILivenessStage)fromLivenessStage to:(AAILivenessStage)toLivenessStage

                  Behavior change since 4.0.0:
                  AAIDetectionType is unavailable and replaced by AAILivenessStage

                  - (void)didStopDetection

                  >=3.4.0 <4.0.0

                  unavailable

                  - (void)detectionDidStopWithSuccess:(AAILivenessSuccessResult *)successResult
                  or
                  - (void)detectionDidStopWithFailure:(AAILivenessFailureResult *)failureResult


                  AAILivenessSDK

                  Method/PropertyVersion RangestatusAlternativeNotes

                  + (void)configUserId:(NSString *)userId

                  >=1.2.0 <4.0.0

                  unavailable

                  livenessConfig.userId

                  + (void)configTicket:(NSString *)ticket

                  >=1.1.0 <4.0.0

                  unavailable

                  livenessConfig.ticket

                  + (void)configQueryId:(NSString *)queryId

                  >=1.1.0 <4.0.0

                  unavailable

                  livenessConfig.queryId

                  + (void)configResultPictureSize:(CGFloat)size

                  >=1.1.2 <4.0.0

                  unavailable

                  livenessConfig.resultPictureSize

                  + (void)configActionTimeoutSeconds:(NSTimeInterval)actionTimeout

                  >=1.1.7 <4.0.0

                  unavailable

                  livenessConfig.timeoutIntervalInSecForAction

                  + (void)configDetectOcclusion:(BOOL)detectOcc

                  >=1.2.0 <4.0.0

                  unavailable

                  livenessConfig.detectOcculsion

                  + (void)configModelBundlePath:(NSString *)modelBundlePath

                  >=1.2.0 <4.0.0

                  unavailable

                  livenessConfig.modelBundlePath

                  + (void)configVideo:(AAIVideoConfig * _Nullable)videoConfig

                  >=2.0.0 <4.0.0

                  unavailable

                  livenessConfig.videoConfig

                  + (nullable AAIVideoConfig *)videoConfig

                  >=2.0.0 <4.0.0

                  unavailable

                  livenessConfig.videoConfig

                  + (nullable AAIVideoRecordResult *)syncGetLatestVideoRecordResult

                  >=2.0.0 <4.0.0

                  unavailable

                  livenessSuccessResult.syncGetVideoRecordResult
                  or
                  livenessFailureResult.syncGetVideoRecordResult

                  + (AAIAdditionalConfig *)additionalConfig

                  >=2.0.0 <4.0.0

                  unavailable

                  livenessViewController.livenessConfig


                  AAILivenessResult

                  AAILivenessResult has been renamed to AAILivenessSuccessResult.

                  Method/PropertyVersion RangestatusAlternativeNotes
                  highestQualityOriginSquareImage>=1.0.0 <4.0.0unavailableRemoved
                  - (NSArray<AAILivenessImageData *> *)imageDataSequenceList>=1.3.5 <2.0.0, >=3.0.7 < 4.0.0unavailableAAILivenessSuccessResult.auditImageDataList

                  AAILivenessFailedResult

                  AAILivenessFailedResult has been renamed to AAILivenessFailureResult, and it has been moved from AAILivenessUI module to AAILivenessSDK module.


                  AAIAdditionalConfig

                  AAIAdditionalConfig has been renamed to AAILivenessConfig.

                  Method/PropertyVersion RangestatusAlternativeNotes
                  roundBorderColor>=2.0.0 <4.0.0unavailablelivenessConfig.normalAvatarBorderColor
                  ellipseLineColor>=2.0.0 <4.0.0unavailablelivenessConfig.innerEllipseDashedLineColor
                  ellipseBorderCol3D>=3.0.0 <4.0.0unavailablelivenessConfig.highlightAvatarBorderColor
                  normalEllipseBorderCol3D>=3.3.0 <4.0.0unavailablelivenessConfig.normalAvatarBorderColor
                  innerEllipseLineCol3D>=3.0.0 <4.0.0unavailablelivenessConfig.innerAnimatedEllipseLineColor
                  detectionLevel>=2.0.1 <4.0.0unavailableRemoved
                  prepareTimeoutInterval>=2.0.4 <4.0.0unavailablelivenessConfig.silentTimeout
                  operatingMode>=3.0.0 <4.0.0unavailableRemoved
                  enableCollectAuditImages>=3.1.0 <4.0.0unavailablelivenessConfig.auditImageConfig.enableCollect
                  auditImageCaptureInterval>=3.1.0 <4.0.0unavailablelivenessConfig.auditImageConfig.imageCaptureInterval
                  auditImageMaxNumber>=3.1.0 <4.0.0unavailablelivenessConfig.auditImageConfig.imageMaxNumber
                  auditImageWidth>=3.1.0 <4.0.0unavailablelivenessConfig.auditImageConfig.imageWidth
                  auditImageQuality>=3.1.2 <4.0.0unavailablelivenessConfig.auditImageConfig.imageQuality
                  relativeSecondsCaptureAfterCameraLaunched>=3.3.0 <4.0.0unavailablelivenessConfig.auditImageConfig.relativeSecondsCaptureAfterCameraLaunched
                  pluginType>=3.4.0 <4.0.0unavailablelivenessConfig.pluginType
                  signatureId>=3.6.0 <4.0.0unavailablelivenessConfig.signatureId

                  AAILivenessWrapView

                  Method/PropertyVersion RangestatusAlternativeNotes
                  detectionActions>=1.0.0 <4.0.0unavailableRemoved
                  - (void)checkCameraPermissionWithCompletionBlk:(void (^_Nullable)(BOOL authed))completionBlk>=1.0.0 <4.0.0unavailableRemoved
                  - (void)startAuthWithCompletionBlk:(void (^_Nullable)(NSError * _Nullable error))completionBlk>=1.2.3 <4.0.0unavailable- (void)startRunningWithConfig:(AAILivenessConfig *)livenessConfig
                  - (void)stopRunningWithReason:(NSString *)reason>=2.0.7 <4.0.0unavailablestopRunning

                  AAILivenessWrapDelegate

                  Method/PropertyVersion RangestatusAlternativeNotes
                  - (void)onOpenCameraFailed:(NSError * _Nonnull)error>=3.0.5 <4.0.0unavailable- (void)onFinalDetectionFailure:(AAILivenessFailureResult * _Nonnull)failureResult
                  - (void)onDetectionFailed:(AAIDetectionResult)detectionResult forDetectionType:(AAIDetectionType)detectionType>=1.0.0 <4.0.0unavailable- (void)onFinalDetectionFailure:(AAILivenessFailureResult * _Nonnull)failureResult
                  - (void)onFrameDetected:(AAIDetectionResult)result status:(AAIActionStatus)status forDetectionType:(AAIDetectionType)detectionType>=1.0.0 <4.0.0unavailableRemoved
                  - (void)onDetectionReady:(AAIDetectionType)detectionType>=1.0.0 <4.0.0unavailableRemoved
                  - (void)onDetectionTypeChanged:(AAIDetectionType)toDetectionType>=1.0.0 <4.0.0unavailable- (void)onLivenessStageChanged:(AAILivenessStage)newLivenessStage
                  - (void)onDetectionRemainingTime:(NSTimeInterval)remainingTime forDetectionType:(AAIDetectionType)detectionType>=1.0.0 <4.0.0unavailable- (void)onDetectionRemainingTimeChanged:(NSInteger)remainingTime forLivenessStage:(AAILivenessStage)livenessStage
                  - (void)onDetectionSuccess>=1.0.0 <4.0.0unavailable- (void)onLivenessStageChanged:(AAILivenessStage)newLivenessStage
                  - (void)onDetectionComplete:(AAILivenessResult * _Nonnull)resultInfo>=1.0.0 <4.0.0unavailable- (void)onFinalDetectionSuccess:(AAILivenessSuccessResult * _Nonnull)successResult