iOS Liveness SDK FAQ

1. How to configure the SDK to use specific languages?

Currently, this SDK supports English (en), Simplified Chinese (zh-Hans), Indonesian (id), Vietnamese (vi), Thai (th), Mexican (es), Bahasa Melayu (ms), Hindi (hi), Filipino(fil).

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.

2. How to customize the UI?

AAILivenessViewControllerprovides some public interfaces and properties for customization, if you want to deep customize the UI or logic, you can inherit fromAAILivenessViewController and override its methods.

For example, you can override the updateStateLabel:key: method to customize the localized string, or override the loadAdditionalUI method to show your own UI elements.

If you want to show your own activity indicator view, you can set the showHUD property of AAILivenessViewController to false, then implement the beginRequestBlk and endRequestBlk of AAILivenessViewController.h to show your own activity indicator view.

For more information, please refer to the demo project LivenessSDKSwiftDemo in the SDK package.

3. 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:

  xxxxxxxxxx
  override func updateStateLabel(_ state: String, key: String) {
      // 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. 
      var lanKey = AAILivenessUtil.currLanguageKey()
      if let language = self.language {
          lanKey = 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 == "th" {
          if key == "move_center" {
              let newState = "กรุณาวางใบหน้าให้อยู่ในจุดศูนย์กลางของกรอบใบหน้า"
              super.updateStateLabel(newState, key: key)
              return
          }
      }
      // Use default translation
      super.updateStateLabel(state, key: key)
  }
  

  xxxxxxxxxx
  - (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];
  }
  

4. How to customize the font?

You can set the font property of AAILivenessViewController to apply a custom font across the detection UI. When set, the font family is applied (while preserving each control's original point size) to:

• _stateLabel — the real-time detection hint label (e.g. "Please blink")
• _timeLabel — the countdown timer label
• The loading HUD label shown during network requests

When font is nil (the default), the SDK uses its built-in system fonts.

xxxxxxxxxx
let livenessViewController = AAILivenessViewController()

// Use any UIFont whose family is registered in the app bundle.
// The SDK will apply the same family at each control's own point size.
livenessViewController.font = UIFont(name: "YourFontPostScriptName", size: 16)

xxxxxxxxxx
AAILivenessViewController *livenessViewController = [[AAILivenessViewController alloc] init];

// Use any UIFont whose family is registered in the app bundle.
livenessViewController.font = [UIFont fontWithName:@"YourFontPostScriptName" size:16];

Note: The size parameter passed to UIFont(name:size:) is not used directly by the SDK — each control applies [font fontWithSize:<controlSize>] internally to keep the original size hierarchy. You may pass any positive value (e.g. 16).

To use a custom .ttf / .otf font, add the font file to your Xcode project, declare it under the UIAppFonts key in Info.plist, and use its PostScript name as the font name. To find the PostScript name, open the font file in Font Book on macOS and look for the "PostScript name" field.

5. How to turn voice prompt on or off?

Configure the livenessViewController.playAudio to enable or disable voice prompt.

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)

7. What are the SDK initialization methods, their differences, and how to use them?

Currently, the SDK has three initialization methods: initialization with license (recommended), initialization with static key (deprecated, not recommended), and initialization with ticket (deprecated, not recommended).

For compatibility reasons, these methods still work in version 4.x, but we recommend using only one initialization method throughout your app's lifecycle. Avoid mixing different initialization methods (although supported, it's not recommended).

Note: If you use different initialization methods in your app, you need to initialize the SDK before each use. For example, after completing the license initialization flow, if you want to use static key initialization, you need to call the corresponding initialization method again, otherwise the SDK will not function properly.

Below are the instructions for each initialization method:

1. License Initialization：This is the recommended method, used as follows:

xxxxxxxxxx
@objc func tapButtonAction() {
  // 1. Init SDK(from 4.1.0)
  // Case 1. License Initialization:
  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. Configure license then check it
  let demoLicenseContent = "your-license-content"
  let checkResult = AAILivenessSDK.configLicenseAndCheck(demoLicenseContent)
  if checkResult == "SUCCESS" {
    // 3. license is valid, create the livenessViewController
    let livenessViewController = AAILivenessViewController()

    // 4. Other optional configurations as needed
    // let livenessConfig = livenessViewController.livenessConfig
    // For example, you can set the liveness type, timeout, signatureId, etc.
    ...

    // Other optional livenessViewController configurations as needed
    ...

    // 5. Implement the `detectionSuccessBlk` and `detectionFailureBlk` of livenessViewController
    ...

    // 6. Push or present the livenessViewController
    ...
  }
}

2. Static key for initialization：This method is deprecated due to the risk of accessKey leakage. It remains available only for compatibility.

xxxxxxxxxx
@objc func tapButtonAction() {
  // 1. Init SDK(from 4.1.0)
  let staticKeyConfig = AAILDStaticKeyModeConfig()
  staticKeyConfig.accessKey = "your-accessKey"
  staticKeyConfig.secretKey = "your-secretKey"
  // Set your market
  staticKeyConfig.market = .indonesia
  // Set whether the SDK is used as a global service
  staticKeyConfig.isGlobalService = false
  AAILivenessSDK.initWith(staticKeyConfig)
  // 2. Create the livenessViewController
  let livenessViewController = AAILivenessViewController()
  // 3. Other optional configurations as needed
  // let livenessConfig = livenessViewController.livenessConfig
  ...

  // 4. Other optional livenessViewController configurations as needed
  ...

  // 5. Implement the `detectionSuccessBlk` and `detectionFailureBlk`
  ...

  // 6. Push or present the livenessViewController
  ...
}

3. Ticket initialization:：This method is deprecated. If upgrading from an older version, refer to the following usage for compatibility.

@objc func tapButtonAction() {
  // 1. Init SDK(from 4.1.0)
  let ticketConfig = AAILDTicketModeConfig()
  // Set your market
  ticketConfig.market = .indonesia
  // Set whether the SDK is used as a global service
  ticketConfig.isGlobalService = false
  AAILivenessSDK.initWith(ticketConfig)
  // 2. Create the livenessViewController
  let livenessViewController = AAILivenessViewController()
  // 3. Set the ticket and queryId
  let livenessConfig = livenessViewController.livenessConfig
  // IMPORTANT: You must set the ticket and queryId when using ticket initialization
  // This is required configurations for ticket initialization
  livenessConfig.ticket = "your-ticket"
  // Optional: Set the queryId if needed for ticket initialization
  /// This is a custom string used to associate the current liveness process.
  /// Note that this field must be paired with the ticket.
  livenessConfig.queryId = "your-query-id"
  // Other optional configurations as needed
  ...

  // Other optional livenessViewController configurations as needed
  ...

  // 4. Implement the `detectionSuccessBlk` and `detectionFailureBlk`
  ...
  
  // 5. Push or present the livenessViewController
  ...
}