iOS 3D Liveness Detection SDK (v3.4.1) User Guide

Development Preparation

1. Contact us to register an account.

Overview

AAILivenessSDK contains four modules, the core module AAILivenessSDK.xcframework, the UI module AAILivenessUI, the resource module Resource, the network module AAINetwork.xcframework. The actual total size of the SDK is about 5.8MB(arm64, disable bitcode).

• AAILivenessSDK.xcframework

  This is a core module, which provides the main functions of SDK, including face detection. The actual total size of the this module is about 3MB(arm64, disable bitcode).

• AAILivenessUI

  This is a UI module, SDK UI is implemented in this module and it's open source, if necessary, you can modify the code here. See Customizable UI and FAQ for how to customize the UI.

• Resource

  This resource module contains images, multi-language files, audio files, and model files. The UI module AAILivenessUI depends on this resource module, during liveness detection, the UI module will load related images and play audio. Note that the core module AAILivenessSDK.xcframework only depends on AAIModel.bundle. This resource folder is about 2MB.

• AAINetwork

  A base network library that AAI SDKs rely on. The actual total size of the this module is about 0.8MB(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: 5.8MB(arm64, disable bitcode)
• Supported bitcode: NO
• Supported languages: en, zh-Hans, id, vi, th, es, ms, hi
• Use-permissions: NSCameraUsageDescription, NSMotionUsageDescription

Migration Guides

1. From version 3.4.0, the SDK only supports iOS 10.0 or higher, and the pod module AAILiveness has been renamed to AAILivenessUI.

2. When migrating from older SDK(1.x.x) to version 2.0.1 or higher, you need to refer the document to reintegrate the SDK. We recommend using the CocoaPods for integration.

3. From version 3.0.0, motion detection has been removed, so the properties and methods related to motion detection will not have any effect.

4. When migrating from 1.2.9 to 1.3.0, you need to add the system library Accelerate.framework and replace all of the SDK files.

5. When migrating from 1.2.8 to 1.2.9, you need to replace all of the SDK files("AAILiveness" folder, "AAILivenessSDK.xcframework" folder, "Resource" folder).

6. When migrating from 1.2.7 (or lower) to 1.2.8 (or higher), you need to add the system library libz.tbd and replace all of the SDK files.

7. From 1.2.3 or higher, AAILivenessViewController provides some public interfaces and properties, when upgrading to this version, you should use its public interfaces to implement your custom logic.

8. If your SDK version is lower than 1.2.0, then after migrating to 1.2.0 or higher, you need to do:

   • Change the parameters of the onDetectionComplete method from NSDictionary to AAILivenessResult.
   • Add AAIModel.bundle resource.
   • Call the [AAILivenessSDK configModelBundlePath:] method to configure the path to the AAIModel.bundle file. You can refer to viewDidLoad method of AAILivenessViewController.m for more details.

9. We recommend you read the change logs to see what has been updated in the new version of the SDK.

Run demo project

1. The demo project is included in the SDK compressed package. Download the AAILivenessSDK and extract it, then navigate to the directory of LicenseMode/LivenessSDKObjCDemo or LicenseMode/LivenessSDKSwiftDemo project and install the dependencies:

   pod install
   

2. Open xcworkspace file in Xcode.

3. Specify your market:

   [AAILivenessSDK initWithMarket:AAILivenessMarket<yourMarket>];
   

4. Specify license content and start SDK, the license content is obtained by your server calling our openapi.

Installation

CocoaPods (Recommended)

1. Specify the SDK name and url in the Podfile:

   pod 'AAINetwork', :http => 'https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-libraries/AAINetwork/AAINetwork-V1.0.3.tar.bz2', type: :tbz 
   pod 'AAILivenessUI', :http => 'https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-liveness-detection/3.4.1/iOS-Liveness-SDK-V3.4.1.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/3.4.1/iOS-Liveness-SDK-V3.4.1.tar.bz2', type: :tbz, :modular_headers => true
   

2. Install the dependencies in your project:

   pod install
   

3. Add camera、motion 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>
   <key>NSMotionUsageDescription</key>
   <string>Use the motion sensor to get the phone orientation</string>
   

   Note that the SDK needs to detect whether the phone is in an upright position, only when the phone is in an upright position will the SDK start detecting face, so you have to add NSMotionUsageDescription in your Info.plist.

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

Manually

1. Download the AAILivenessSDK and AAINetwork, then uncompress them and add AAILivenessSDK folder, AAINetwork.xcframework to your project:

   

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

3. Choose "TARGETS -> General -> Frameworks,Libraries,and Embedded Content", then set AAILivenessSDK.xcframework and AAINetwork.xcframework's Embed as "Embed & Sign".

4. Add -ObjC to the other linker flag in the project configuration.

5. Add camera and motion sensor (gyroscope) 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>
   <key>NSMotionUsageDescription</key>
   <string>Use the motion sensor to get the phone orientation</string>
   

   Note that the SDK needs to detect whether the phone is in an upright position, only when the phone is in an upright position will the SDK start detecting face, so you have to add NSMotionUsageDescription in your Info.plist.

Usage

1. Import SDK and initialize with your market:

   // For pod integration
   @import AAILivenessUI;
   
   /*
   // For manually integration
   #import <AAILivenessSDK/AAILivenessSDK.h>
   #import "AAILivenessViewController.h"
   #import "AAILivenessFailedResult.h"
   */
   
   /*
   If you need the SDK as a global service, 
   you should use the initialization method `initWithMarket:isGlobalService:` 
   and pass YES to the `isGlobalService` parameter.
    */
   [AAILivenessSDK initWithMarket:AAILivenessMarket<yourMarket>];
   
   // Configure SDK
   
   // 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.
   [AAILivenessSDK configUserId:@"your-user-id"];
   
   /*
   // Set the size(width) of `img` in `AAILivenessResult`. Image size(width) should be in range [300, 1000], default image size(width) is 600(600x600).
   [AAILivenessSDK configResultPictureSize:600];
   */
    
   /*
   // Set whether to detect face occlusion. The default value is NO.
   [AAILivenessSDK configDetectOcclusion:YES];
   */
   
   /*
    AAIAdditionalConfig *additionalConfig = [AAILivenessSDK additionalConfig];
    
    /// The color of the ellipse border in 3D mode(near/distant mode). Default is 0x5CC414.
    // additionalConfig.ellipseBorderCol3D = [UIColor blueColor];
   
    /// The color of the inner ellipse animation line of the 3D mode(near/distant mode). Default is 0x5CC414.
    // additionalConfig.innerEllipseLineCol3D = [UIColor redColor];
   
    */
   

2. Configure SDK license and show SDK page:

   
   // The license content is obtained by your server calling our openapi.
   NSString *checkResult = [AAILivenessSDK configLicenseAndCheck:@"your-license-content"];
   if ([checkResult isEqualToString:@"SUCCESS"]) {
      // license is valid, show SDK page
      AAILivenessViewController *vc = [[AAILivenessViewController alloc] init];
   
      /*
      // Specify which language to use for the SDK.
      // The languages currently supported by sdk are as follows:
      // "en" "id"  "vi"  "zh-Hans"  "th"  "es"  "ms" "hi"
      vc.language = @"id";
      */
   
      /*
      /// Set the detection timeout duration of 3D mode(near/distant mode), default is 50s.
      ///
      /// If the detection cannot pass within this time duration,  the `detectionFailedBlk` will be called,
      /// and the value of the "key" in errorInfo is "fail_reason_prepare_timeout".
      ///
      /// @note This time duration does not include network request duration.
      ///
      vc.timeoutDurationOf3DMode = 50;
      */
   
      /*
      /// Whether to allow to play prompt audio, the default is YES.
      vc.playAudio = NO;
      */
   
      /*
      /// Whether to mark the action of tapping back button as "user_give_up". The default is NO. If you set YES, the `detectionFailedBlk`
      /// will be called when the user taps the top left back button while liveneness detection is running.
      vc.recordUserGiveUp = YES;
      */
   
      vc.detectionSuccessBlk = ^(AAILivenessViewController * _Nonnull rawVC, AAILivenessResult * _Nonnull result) {
         // Get livenessId
         NSString *livenessId = result.livenessId;
         // Get eventId(You should save this ID in case of tracking problems).
         NSString *eventId = result.eventId;
   
         // The best quality face image captured by the SDK. Note that the default image size is 600x600.
         UIImage *bestImg = result.img;
         CGSize size = bestImg.size;
         NSLog(@">>>>>livenessId: %@, imgSize: %.2f, %.2f", livenessId, size.width, size.height);
   
         // A small square image containing only the face area, image size is 300x300.
         UIImage *fullFaceImg = result.fullFaceImg;
   
         // Do something... (e.g., call anti-spoofing api to get score)
   
         [rawVC.navigationController popViewControllerAnimated:YES];
      };
   
      /*
      // If you don't implement the `detectionFailedBlk`, the SDK will go to the `AAILivenessResultViewController` when liveness detection fails. 
      // You can implement this block to go to your custom result page or process error information.
      vc.detectionFailedBlk = ^(AAILivenessViewController * _Nonnull rawVC, NSDictionary * _Nonnull errorInfo) {
         AAILivenessFailedResult *result = [AAILivenessFailedResult resultWithErrorInfo:errorInfo];
         // Get eventId(You should save this ID in case of tracking problems).
         NSString *eventId = result.eventId;
   
         NSLog(@"Detection failed: %@, message: %@, transactionId: %@, eventId: %@", result.errorCode, result.errorMsg, result.transactionId, eventId);
         
         // Close SDK page ...
         [rawVC.navigationController popViewControllerAnimated:YES];
      };
      */
   
      // Demo: Push SDK page.
      [self.navigationController pushViewController:vc animated:YES];
   
      /*
      // Demo: Present SDK page.
      UINavigationController *navc = [[UINavigationController alloc] initWithRootViewController:vc];
      navc.navigationBarHidden = YES;
      navc.modalPresentationStyle = UIModalPresentationFullScreen;
      [self presentViewController:navc animated:YES completion:nil];
      */
   } else if ([checkResult isEqualToString:@"LICENSE_EXPIRE"]) {
      // "LICENSE_EXPIRE"
   } else if ([checkResult isEqualToString:@"APPLICATION_ID_NOT_MATCH"]) {
      // "APPLICATION_ID_NOT_MATCH"
   } 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.
       */
   
   }
   

Error code

The errorCode values of AAILivenessFailedResult are as follows:

Customizable UI

1. UI Cutomization.

   File name	File description	Customizable description
   AAILivenessViewController.m	Detection page	You can implement custom UI and other logic by inheriting from this class. See the demo project for how to customize the UI.
   AAILivenessResultViewController.m	Detection result page	All UI elements can be customized. If necessary, you can implement the detectionSuccessBlk and detectionFailedBlk of AAILivenessViewController.h to enter your own app page instead of this result page
   AAIHUD.m	Activity Indicator View	All UI elements can be customized. If necessary, you can set the showHUD property of AAILivenessViewController to NO, then implement the beginRequestBlk and endRequestBlk of AAILivenessViewController.h to show your own activity indicator view

   For more information on how to customize the UI, please refer to the question in the FAQ.

2. Resources File Customization. Currently, this SDK supports English (en), Simplified Chinese (zh-Hans), Indonesian (id), Vietnamese (vi), Thai (th), Mexican (es), Bahasa Melayu (ms) and Hindi (hi). The SDK will use the corresponding resource file according to the current language of the device. If this device language is not in the above languages, the SDK will use English by default. If you want to support only a fixed language, you can set the language property of AAILivenessViewController. The resource files corresponding to these languages are in the following bundles:

   Name	Description	Customizable description
   AAILanguageString.bundle	Muti-language bundle	See the FQA for how to customize the customize the localized string.
   AAIAudio.bundle	Audio bundle	Use your audio file to replace it. NOTE: the audio file name cannot be changed
   AAIImgs.xcassets	Image bundle	Use your image file to replace it. NOTE: the image file name cannot be changed
   AAIModel.bundle	Model bundle	Cannot be modified

FAQ

1. If you add an All Exceptions breakpoint, the code could stop at player = [[AVAudioPlayer alloc] initWithContentsOfURL:url error:&error];, Line 163 of file AAILivenessUtil.m. during face detection actions. The solution is to find All Exceptions breakpoint and edit the exception type from "All" to "Objective-C", as shown by figure below.

   

2. The earliest supported iOS version is iOS9, and don't support bitcode.

3. Can I customize the UI? Yes. From 1.2.3 or higher, AAILivenessViewController provides some public interfaces and properties, see demo project for how to customize UI or logic. For 1.2.2 or lower, AAILivenessViewController does not provide an extensible UI, so you need to modify the source code to meet your requirements. In addition, AAILivenessResultViewController is just a display result page. Normally, you can implement the detectionSuccessBlk and detectionFailedBlk of class AAILivenessViewController to jump to your own app page instead of the AAILivenessResultViewController page.

4. How to customize the localized string?

   There are two ways to customize the localized string:

   • Add the AAILiveness.strings file to your main bundle(Recommanded).

     1. Open the project by Xcode, File->New->File->StringFile, named AAILiveness.strings.
     2. In Xcode, select the AAILiveness.strings file, in the panel on the right, you can see the Localization section, and check the languages you want to support.
     3. If you want to add a new language, select your PROJECT, in the Info panel, you can find the Localization section, click the +, select your target language, and in the subsequent session window, check the AAILiveness.strings file and click Next. This ensures that the language file you added can be correctly loaded by the SDK.
     4. You can find the en.lproj folder in the root directory after decompressing the downloaded tar.bz2 file, which contains the Localizable.strings file, and this file contains all the key-value of the text used by the SDK.
     5. You can add key-value of the localized text, SDK will priorly load the key-value in this file.
     6. If a key is not found in your file, then the SDK will use the default value. You just need to add the key-value that you want to modify to this file.

   • Using code to customize the localized string.

     You can create a subclass of AAILivenessViewController, then override the updateStateLabel:key: method to customize the localized string, finally present your subclass of AAILivenessViewController instead of the default AAILivenessViewController. For example, if you want to customize the translation of the localized key move_center in Thai(th.lproj), you can do it like this:

     - (void)updateStateLabel:(NSString *)state key:(NSString *)key
     {
        // The languages currently supported by sdk are as follows:
        // "en" "id"  "vi"  "zh-Hans"  "th"  "es"  "ms" "hi"
        // The SDK will use the corresponding resource file according to the current language of the device. 
        // If this device language is not in the above languages, the SDK will use English by default. 
        NSString *lanKey = [AAILivenessUtil currLanguageKey];
        if (self.language) {
           lanKey = self.language;
        }
     
        // All available localized keys are located in the 'en.lproj' file.
        //
        // For example, if you want to customize the translation text corresponding
        // to the localized key 'move_center' in Thai(th.lproj), you can do it like this.
        if ([lanKey isEqualToString:@"th"]) {
           if ([key isEqualToString:@"move_center"]) {
                 NSString *newState = @"กรุณาวางใบหน้าให้อยู่ในจุดศูนย์กลางของกรอบใบหน้า";
                 [super updateStateLabel:newState key:key];
                 return;
           }
        }
        // Use default translation
        [super updateStateLabel:state key:key];
     }
     

5. If I have modified the UI part of the code, how do I upgrade to the new version of the SDK? Usually, only AAILivenessSDK.xcframework will be updated when the SDK is updated, the external open source code will not be modified. If the external open source code is modified in the new version of SDK, there will be detailed instructions in the release log, so you need to read the release log carefully to see if the external code has been modified.

6. Error: Access for this account is denied You need to bind your app bundleId to the accessKey secretKey on our CMS website.(Personal Management -> ApplicationId Management)

Change logs and release history

See iOS liveness SDK release history