Cordova liveness detection plugin
Cordova aai-ios-liveness-detection-plugin(v4.0.0)
Migration Guides
- 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.
- From version 3.1.3, the method
onLivenessViewRequestFailed
have been removed, and the parametererrorCode
(old version called 'key') ofonDetectionFailed
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
-
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
). -
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 errorCode | new errorCode | Description |
---|---|---|
PREPARE_TIMEOUT | ACTION_TIMEOUT | Replaced by ACTION_TIMEOUT |
MUTI_FACE | MUTIPLE_FACE | Renamed |
NO_RESPONSE | AUTH_NETWORK_ERROR_$ErrorCode or UPLOAD_IMAGE_DATA_NETWORK_ERROR_$ErrorCode | We have subdivided the original NO_RESPONSE error code into multiple error codes. |
Change logs and release history
v4.0.0 Download
Break changes
- 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.
- The callback methods
onCameraPermissionDenied
,onDetectionReady
,onDetectionTypeChanged
have been removed. You can use theonDetectionFailed
method to handle the camera permission denied event. - The
errorCode
ofonDetectionFailed
has been changed, please refer to the Error code for details.
v3.6.1 Download
Update
- Sync native SDK.
v3.6.0 Download
Update
- Sync native SDK.
- Add
setSignatureId
method.
v3.5.0 Download
Update
- Sync native SDK.
v3.4.1 Download
Update
- Sync native SDK.
v3.4.0 Download
Update
- Sync native SDK.
- Add
setHudBrandColor
method, which is used to set the color ofAAILoadingHud
. The default is #5BC413.
v3.3.0 Download
Update
- Sync native SDK.
New Features
- 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
- Remove the callback method
onLivenessViewRequestFailed
, please useonDetectionFailed
to handle the user's give up action and network request failed. - The
errorCode
ofonDetectionFailed
has been changed, please refer to the Error code for details.
New Features
- Added
additionalInfo
parameter toonDetectionFailed
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.
- Added
additionalInfo
parameter toonDetectionComplete
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.
- 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, theonDetectionFailed
will be called when the user taps the top left back button while liveneness detection is running. - Added method
setAuditImageConfig
andsetVideoRecorderConfig
to support collecting audit images and recording video during the detection process.
Update
- Sync native SDK.
v3.1.2 Download
- Sync native SDK.
v3.1.1 Download
- Sync native SDK.
v3.1.0 Download
- Sync native SDK.
v3.0.7 Download
- Sync native SDK.
- Support market
BPS
. - Add methods
setEllipseBorderCol3D
andsetInnerEllipseLineCol3D
.
v3.0.5 Download
- Sync native SDK.
- Upgrade AAINetwork module to 1.0.2.
v3.0.4 Download
- Sync native SDK.
v3.0.3 Download
- Sync native SDK.
v3.0.2 Download
- Sync native SDK.
v3.0.0 Download
- Sync native SDK.
- 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
- Sync native SDK.
v2.0.6 Download
- Sync native SDK.
v2.0.5 Download
- Sync native SDK.
v2.0.4 Download
- Sync native SDK.
- Add methods
setPlayPromptAudio
andsetShowAnimationImgs
.
v2.0.3 Download
- Sync native SDK.
v2.0.2 Download
- Sync native SDK.
- Add methods
setDetectionLevel
,setRoundBoderColor
,setEllipseLineColor
.
v1.3.4 Download
- Sync native SDK.
v1.3.3 Download
- Optimizing the capture of face image.
- Support closed eye detection.
- Add localized string "pls_open_eye".
- Fix EXC_BAD_ACCESS bug that could occur in some cases.
- Fix the global service bug.
- Compressed images of AAIImgs.bundle.
v1.2.9 Download
- Add methods
setActionTimeoutInterval
,setPrepareTimeoutInterval
,setLanguage
. - Update Resource.
v1.2.8 Download
- Upgrade network module.
- Set the SDK view to be displayed in full screen.
v1.2.7 Download
- Updated license check feature.
v1.2.6 Download
- Set the width of the image output by the SDK from 300 to 600.
v1.2.5 Download
- Refacored AAILivenessViewController.
- Fix EXC_BAD_ACCESS bug that could occur in some cases.
- Add other market enum values.
v1.2.1 Download
- Fix the bug that img of AAILivenessResult may be nil when the onDetectionComplete: method is called.
v1.2.0 Download
- Support to initialize SDK with license.
- 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.
- Support Mexico,Malaysia,Pakistan,Nigeria,Colombia.
- Added the
AAIModel.bundle
resource.
Updated 10 days ago