Documentation

Cordova liveness detection plugin

Cordova aai-ios-liveness-detection-plugin(v4.0.0)

Migration Guides

  1. From version 4.0.0, we've introduced significant API improvements and feature enhancements. We introduce a configuration map to conveniently set various parameters, replacing the previous method-based configuration approach. This change simplifies the configuration process and enhances flexibility. Please refer to the Usage section for the details.
  2. From version 3.1.3, the method onLivenessViewRequestFailed have been removed, and the parameter errorCode(old version called 'key') of onDetectionFailed has been changed, please refer to the v3.1.3 change logs for details.

Download plugin

See this part to get plugin download link.

Installation

  1. Add local plugin to your project:

    # remove exist liveness detection plugin if needed. 
    cordova plugin remove aai-ios-liveness-detection-plugin
    
    cordova plugin add /path/to/guardian-liveness-detection-cordova-plugin-ios

    If you get error like "CordovaError: Could not determine package name from output", try using a lower version of npm(e.g. nvm install 14.19.0).

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


document.addEventListener('deviceready', onDeviceReady, false);

function onDeviceReady() {
    document.getElementById('test-liveness-button').addEventListener('click', tapShowSDKButtonAction)

    var plugin = cordova.plugins.AAIIOSLivenessDetectionPlugin

    // Get SDK version (optional)
    plugin.getSdkVersion(function(version) {
        console.log(version)
        document.getElementById('test-liveness-button').innerHTML = version + '-liveness-sdk-test'
    })
}

function configSDKCallback() {
    var plugin = cordova.plugins.AAIIOSLivenessDetectionPlugin

    /* Required */
    plugin.onDetectionComplete(function(livenessId, base64ImgStr, additionalInfo) {
        //close liveness page
        plugin.closeSDKPage()

        console.log('onDetectionComplete:', livenessId)
        console.log('additionalInfo:', additionalInfo)
        console.log('eventId', addtionalInfo.eventId)

        /*
        You need to give the livenessId to your server, then your server will call the anti-spoofing api to get the score of this image.
        The default base64Img size is 600x600.

        The parameter 'additionalInfo' contains the following keys:
           - 'eventId': This used to help debug the specific cause of the error.
           - 'transactionId': This is used to help debug the specific cause of the server side error.
           - 'videoFilePath': The video file path, if you enable the video recording feature, otherwise this key will not exist.
        */
    })

    /* Required */
    plugin.onDetectionFailed(function(errorCode, message, additionalInfo) {
        //close liveness page
        plugin.closeSDKPage()

        console.log('onDetectionFailed:', errorCode, message)
        console.log('additionalInfo:', additionalInfo)
        console.log('eventId', addtionalInfo.eventId)
    })

    /*
    // Optional
    plugin.onLivenessViewBeginRequest(function() {
        console.log('onLivenessViewBeginRequest')
    })
    */

    /*
    // Optional
    plugin.onLivenessViewEndRequest(function() {
        console.log('onLivenessViewEndRequest')
    })
    */
}

function showLivenessView() {
    //Show SDK Page.
    /*
    By default, this page is displayed modally.
    If you need other presentation type, please modify the 'showSDKPage:' method in 'AAIIOSLivenessDetectionPlugin.m'
    */

   var config = {
     /*
      /// Optional
      ///  You can customize the width of the avatar preview area by setting this value.
      // Note that the avatar area is always square and horizontally centered.
      avatarPreviewWidth: 250
      */

     /*
      /// Optional
      avatarPreviewMarginTop: 64
      */

      /*
      /// Optional
      showHUD: true,
      */

      /*
      /// Optional
      /// Specify which language to use for the SDK. If this value is not set,
      /// the system language will be used by default. If the system language is not supported,
      /// English will be used.
      ///
      /// The languages currently supported by sdk are as follows:
      /// 
      /// "en" "id"  "vi"  "zh-Hans"  "th"  "es"  "ms" "hi"
      language: "en",
      */
      
      /*
      /// Optional
      /// This value represents the timeout interval during the distant near stage.
      ///
      /// @warning The range of values should be [10s, 60s], default is 50s.
      ///
      /// @since 4.0.0
      distantNearTimeout: 50,
      */

      /*
      /// Optional
      /// This value represents the timeout interval during the silent(preparation) stage.
      ///
      /// @warning The range of values should be [10s, 60s], default is 50s.
      ///
      /// @since 4.0.0
      silentTimeout: 50,
      */

      /*
      /// Optional
      /// This value represents the timeout interval for action detection, the default is 10s.
      ///
      /// @warning The range of values should be [10s, 60s], default is 10s.
      ///
      /// @since 4.0.0
      actionTimeout: 10,
      */

      /*
      /// Optional
      // Whether to animate the presentation. Default is true.
      animated: true,
      */

      /*
      /// Optional
      // Whether to display animation images. Default is true. If you set false, then animation images will be hidden.
      showAnimationImg: true
      */
      
     /*
      /// Optional
      // Whether to allow to play prompt audio. Default is true.
      playPromptAudio: true,
      */

      /*
      /// Optional
      /// The highlight color of the ellipse border in 3D mode(near/distant mode). Default is #F5F5F5.
      ///
      /// @since 4.0.0
      normalAvatarBorderColor: "#AABBFF",
      */

     /*
      /// Optional
      /// The hightlight state color of the avatar preview area's border. The default is #5BC413.
      ///
      /// @since 4.0.0
      highlightAvatarBorderColor: "#FF0000",
      */
     
      /*
      /// Optional
      /// The hightlight color of the inner ellipse animation line of the 3D mode(near/distant mode). Default is 0x5BC413.
      ///
      /// @since 4.0.0
      innerAnimatedEllipseLineColor: "#0000FF",
      */
      
      /*
      /// Optional
      /// The color of the ellipse dashed line that appears during the liveness detection. Default is white color.
      ///
      /// @since 4.0.0
      innerDashedEllipseLineColor: "#FF0000",
      */

      /*
      /// Optional
      /// Specify AAILoadingHud brand color. Default is #5BC413.
      /// @since 3.4.0
      hudBrandColor: "#FFC413",
      */

      /*
      /// Optional
      /// The size(width) of the resulting image. Default result image size is 600x600
      ///
      /// @note
      /// This value can be set in the interval [300, 1000], the larger the value, the more memory the SDK will consume.
      ///
      /// @since 4.0.0
      resultPictureSize: 600,
      */

      /*
      /// Optional
      /// User binding (strongly recommended).
      /// You can use this property 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.
      ///
      /// @since 4.0.0
      userId: "your-reference-id",
      */

      /*
      /// Optional
     /// Whether to mark the action of tapping back button as "USER_GIVE_UP". The default is false. If you set true, the `onDetectionFailed`
     /// will be called when the user taps the top left back button while liveneness detection is running.
     recordUserGiveUp: true,
      */

     /*
     /// Optional
     /// An optional string value used to conveniently query liveness detection results.
     /// Call the `/liveness/generate-signature-id` API to generate this value, then assign it to
     /// this field before starting a new liveness flow.
     ///
     /// @warning The value must be unique per liveness flow. Passing a previously used value will result in a parameter error in SDK.
     ///
     /// @since 3.6.0
     signatureId: "my-unique-signature-id",
     */

    /*
     // Optional, specify the liveness type
     /// @since 4.0.0
     livenessType: "your-liveness-type", 
     */

     /*
     // Optional 
     // If you enable this feature, the SDK will automatically upload the audit image sequence list to the server after liveness detection complete. 
     // You can obtained the 'auditImageUrl' fileld in the liveness-detection openapi response. See liveness-detection openapi for more detail.
     // 
     auditImageConfig: {
       enableCollect: true, //Whether to collect audit images. Default is false.
        captureInterval: 400, // Minimum interval time for capturing images, default interval is 400ms
        maxNumber: 10, // Maximum number of captured images, default number is 10
        imageWidth: 400, // The image width, default width is 400px
        imageQuality: 30 // The image compress quality, must in [30,100], the default value is 30
     },
      */

     /*
      // Optional
      // If you enable this feature, SDK will record video during the detection process. 
      // After the completion of the liveness process, you can retrieve the 'videoFilePath' by parse the 'additionalInfo' 
      // in 'onDetectionComplete' callback.
      // The video file format is .mp4. Please note that this video can only be obtained through the SDK and 
      // cannot be obtained from the aai backend. After using the video, it is up to you to decide whether to delete the local file.
      // 
      videoRecorderConfig: {
        enableRecord: false, // Whether to record video. Default value is false.
        maxDuration: 60 // The maximum recording duration, in seconds, valid range [2,60], default is 60 seconds.
      },
      */
     
    }

   cordova.plugins.AAIIOSLivenessDetectionPlugin.showSDKPage(config)
}

function tapShowSDKButtonAction() {
    var plugin = cordova.plugins.AAIIOSLivenessDetectionPlugin

    // 1.Init SDK with license and market(required)
    // Your server needs to call openAPI to obtain license content
    var license = "your-license-content"
    /*
    Market available value are as follows:
    Indonesia
    India
    Philippines
    Vietnam
    Thailand
    Mexico
    Malaysia
    Pakistan
    Nigeria
    Colombia
    Singapore
    BPS
    */
    var market = plugin.MARKET.Indonesia
    plugin.initSDKWithLicenseAndMarket(license, market, (result) => {
        if (result === 'SUCCESS') {
            // 2.Config SDK callback methods
            configSDKCallback()
            // 3.Show SDK Page
            showLivenessView()
        } else {
            document.getElementById('sdk-callback-msg').innerHTML = 'initSDKWithLicenseAndMarket:' + result
        }
        
    })     
}

Error code

Note the following error codes have been changed since version 4.0.0. For all error codes, please refer to this documentation.

old errorCodenew errorCodeDescription
PREPARE_TIMEOUTACTION_TIMEOUTReplaced by ACTION_TIMEOUT
MUTI_FACEMUTIPLE_FACERenamed
NO_RESPONSEAUTH_NETWORK_ERROR_$ErrorCode or UPLOAD_IMAGE_DATA_NETWORK_ERROR_$ErrorCodeWe have subdivided the original NO_RESPONSE error code into multiple error codes.

Change logs and release history

v4.0.0 Download

Break changes
  1. From version 4.0.0, we've introduced significant API improvements and feature enhancements. We introduce a configuration map to conveniently set various parameters, replacing the previous method-based configuration approach. This change simplifies the configuration process and enhances flexibility. Please refer to the Usage section for the details.
  2. The callback methods onCameraPermissionDenied, onDetectionReady, onDetectionTypeChanged have been removed. You can use the onDetectionFailed method to handle the camera permission denied event.
  3. The errorCode of onDetectionFailed has been changed, please refer to the Error code for details.

v3.6.1 Download

Update
  1. Sync native SDK.

v3.6.0 Download

Update
  1. Sync native SDK.
  2. Add setSignatureId method.

v3.5.0 Download

Update
  1. Sync native SDK.

v3.4.1 Download

Update
  1. Sync native SDK.

v3.4.0 Download

Update
  1. Sync native SDK.
  2. Add setHudBrandColor method, which is used to set the color of AAILoadingHud. The default is #5BC413.

v3.3.0 Download

Update
  1. Sync native SDK.
New Features
  1. Added setNormalEllipseBorderCol3D method, which is used to set the normal color of the ellipse border in 3D mode(near/distant mode). The default is 0xF5F5F5.
    If you want to maintain the previous interaction effect, you can call the following codes:
    // Other configurations
    ...
    plugin.setEllipseBorderCol3D("#5BC413")
    plugin.setNormalEllipseBorderCol3D("#5BC413")

v3.1.3 Download

Breaking Changes
  1. Remove the callback method onLivenessViewRequestFailed, please use onDetectionFailed to handle the user's give up action and network request failed.
  2. The errorCode of onDetectionFailed has been changed, please refer to the Error code for details.
New Features
  1. Added additionalInfo parameter to onDetectionFailed method, which contains the following keys:
    • "eventId": This is used to help debug the specific cause of the error.
    • "rawErrorCode": The native sdk side raw error code.
    • "transactionId": This is used to help debug the specific cause of the server side error.
  2. Added additionalInfo parameter to onDetectionComplete method, which contains the following keys:
    • "eventId": This is used to help debug the specific cause of the error.
    • "transactionId": This is used to help debug the specific cause of the server side error.
    • "videoFilePath": The video file path, if you enable the video recording feature, otherwise this key will not exist.
  3. Added recordUserGiveUp method, which is used to mark the action of tapping back button as "USER_GIVE_UP". The default is false. If you pass true, the onDetectionFailed will be called when the user taps the top left back button while liveneness detection is running.
  4. Added method setAuditImageConfig and setVideoRecorderConfig to support collecting audit images and recording video during the detection process.
Update
  1. Sync native SDK.

v3.1.2 Download

  1. Sync native SDK.

v3.1.1 Download

  1. Sync native SDK.

v3.1.0 Download

  1. Sync native SDK.

v3.0.7 Download

  1. Sync native SDK.
  2. Support market BPS.
  3. Add methods setEllipseBorderCol3D and setInnerEllipseLineCol3D.

v3.0.5 Download

  1. Sync native SDK.
  2. Upgrade AAINetwork module to 1.0.2.

v3.0.4 Download

  1. Sync native SDK.

v3.0.3 Download

  1. Sync native SDK.

v3.0.2 Download

  1. Sync native SDK.

v3.0.0 Download

  1. Sync native SDK.
  2. From version 3.0.0, motion detection has been removed, so the properties and methods related to motion detection will not have any effect.

v2.0.7 Download

  1. Sync native SDK.

v2.0.6 Download

  1. Sync native SDK.

v2.0.5 Download

  1. Sync native SDK.

v2.0.4 Download

  1. Sync native SDK.
  2. Add methods setPlayPromptAudio and setShowAnimationImgs.

v2.0.3 Download

  1. Sync native SDK.

v2.0.2 Download

  1. Sync native SDK.
  2. Add methods setDetectionLevel, setRoundBoderColor, setEllipseLineColor.

v1.3.4 Download

  1. Sync native SDK.

v1.3.3 Download

  1. Optimizing the capture of face image.
  2. Support closed eye detection.
  3. Add localized string "pls_open_eye".
  4. Fix EXC_BAD_ACCESS bug that could occur in some cases.
  5. Fix the global service bug.
  6. Compressed images of AAIImgs.bundle.

v1.2.9 Download

  1. Add methods setActionTimeoutInterval, setPrepareTimeoutInterval, setLanguage.
  2. Update Resource.

v1.2.8 Download

  1. Upgrade network module.
  2. Set the SDK view to be displayed in full screen.

v1.2.7 Download

  1. Updated license check feature.

v1.2.6 Download

  1. Set the width of the image output by the SDK from 300 to 600.

v1.2.5 Download

  1. Refacored AAILivenessViewController.
  2. Fix EXC_BAD_ACCESS bug that could occur in some cases.
  3. Add other market enum values.

v1.2.1 Download

  1. Fix the bug that img of AAILivenessResult may be nil when the onDetectionComplete: method is called.

v1.2.0 Download

  1. Support to initialize SDK with license.
  2. Support face occlusion detection(only in the preparation phase, not in the action detection phase), this feature is off by default, you can turn it on if needed.
  3. Support Mexico,Malaysia,Pakistan,Nigeria,Colombia.
  4. Added the AAIModel.bundle resource.