voltmx.localAuthentication Namespace
voltmx.localAuthentication Namespace
The voltmx.localAuthentication namespace provides the functions to authenticate, get the status of the authentication, and cancel authentication.
Note: Applicable for iOS: For information about how to enable the Face ID feature in your VoltMX Iris application, click here. For information about how to detect whether a device supports either the Touch ID or Face ID feature or the Iris authentication, refer the getBiometryType API.
Important: If you have used the Local authentication API in your VoltMX Iris projects, before moving your project to the V9.2 release, ensure that you read the Local Authentication Migration guidelines article.
This namespace contains the following API elements.
Functions
The voltmx.localAuthentication namespace provides the following functions.
voltmx.localAuthentication.authenticate
The API is used to authenticate the user with configurable system UI.
Note: Call the
voltmx.localAuthentication.authenticateAPI only if the[voltmx.localAuthentication.getStatusForAuthenticationMode](#getStatusForAuthenticationMode)API returns the success status code (5000).
Syntax
voltmx.localAuthentication.authenticate(
authenticationMode,
statusCallback,
configMap);
Input Parameters
| Parameter | Description |
|---|---|
| authenticationMode | Specifies the biometric authentication mode for which the status is requested. The data type is constant. For the authentication modes, see Authentication Modes. |
| statusCallBack (status, message) | A callback function that conveys the status of the authentication with an appropriate status code, message, and an info object that contains more information about the authentication. The default value is nil. For status code, see the Status Codes section. info: An object that contains more information about the authentication. The info object uses the following key: authenticationType: Provides information about the type of authentication (either biometrics or device credentials) that the user has configured for authentication. The authenticationType parameter returns one of the following constants: If the authentication fails, the authenticationType parameter returns a null value. |
| configMap | Specifies the configuration dictionary for the system authentication UI. The configMap parameter uses the following keys The value of this key is set to constantsLOCAL_AUTHENTICATION_POLICY_DEV_OWNER_AUTH_WITH_BIOMETRICS, by default. This is an optional key.Depending on the type of local authentication policy, the policy key can have the following values:
Note: Note: When you configure the authenticators key, the device ignores the deviceCredentialAllowed property. Note: As this key acts as a hint to the system, the system may choose to ignore this flag. If the system chooses to ignore this flag, it will require confirmation, by default. For example, if you disable implicit authentication in the settings, or if it does not apply to a modality (e.g. Fingerprint), the System may choose to ignore this key. A typical use case for not requiring confirmation would be low-risk transactions, such as re-authenticating a recently authenticated application. Likewise, A typical use case for requiring confirmation would be for authorizing a purchase. This is an optional key applicable only for devices running on Android Q and later versions. Note: When you set the deviceCredentialsAllowed key or specify DEVICE_CREDENTIAL as the value for the authenticators key, the negativeButtonText property is ignored, |
Example
function statusCB(status, message) {
if (status == 5000) {
voltmx.ui.Alert({
message: "AUTHENTICATION SUCCESSFULL",
alertType: constants.ALERT_TYPE_INFO,
yesLabel: "Close"
}, {});
}
else {
var messg = status + message;
voltmx.ui.Alert({
message: messg,
alertType: constants.ALERT_TYPE_INFO,
yesLabel: "Close"
}, {});
}
}
function authUsingTouchID() {
var configMap = {
"promptMessage": "PLEASE AUTHENTICATE USING YOUR TOUCH ID",
"fallbackTitle": "Please enter your Password"
"description": "Description",
"policy": constants.LOCAL_AUTHENTICATION_POLICY_DEV_OWNER_AUTH_WITH_BIOMETRICS,
"subTitle": "sub title",
"deviceCredentialAllowed": true,
"confirmationRequired": true,
"negativeButtonText": "Negative"
};
voltmx.localAuthentication.authenticate(constants.LOCAL_AUTHENTICATION_MODE_BIOMETRICS, statusCB, configMap);
}
Note: The fallbackTitle and policy keys are only available for the iOS platform. The subTitle, deviceCredentialAllowed, confirmationRequired, and negativeButtonText keys are only available for the Android platform.
Return Values
No
Remarks
Note: For iOS devices, depending on the type of biometric authentication available, the promptMessage is either PLEASE AUTHENTICATE USING YOUR TOUCH ID or PLEASE AUTHENTICATE USING YOUR FACE ID. You can know the type of biometric authentication available using the getBiometyType API.
Note: If you assign an empty string, “ ” to the fallbackTitle key, the Enter Password button will be hidden. If the fallbackTitle key is not defined in the configMap parameter, the default (Enter Password) value is displayed.
Platform Availability
- iOS
- Android
voltmx.localAuthentication.checkFeatureAvailability
The checkFeatureAvailability API provides information about the availability of local authentication-related system features in the device.
This API only indicates whether the device supports the specified feature. It does not indicate whether the feature is enabled or if the corresponding authentication data is registered with the device.
Syntax
voltmx.localAuthentication.checkFeatureAvailability();
Input Parameters
One or more values of face, fingerprint, iris as a list.
Example
var result = voltmx.localAuthentication.checkFeatureAvailability(["face", "fingerprint", "iris"]); if (result.fingerprint == voltmx.localAuthentication.FEATURE_AVAILABLE) { alert("Fingerprint system feature is present in the device"); }
Return Values
A key-value pair in a JS object. The key is any of the face, fingerprint, or iris values. The value is any of the following constants:
Return Value Description voltmx.localAuthentication.FEATURE_AVAILABLE The API returns this constant when the device supports the specified system feature. voltmx.localAuthentication.FEATURE_NOT_AVAILABLE The API returns this constant when the device does not support the specified system feature. voltmx.localAuthentication.FEATURE_UNKNOWN The API returns this constant if the specified feature is unsupported on the device, The API can detect support for the face and iris features in devices that run on Android 10 (API level 29), and later versions. Support to detect the fingerprint feature is present in Android 6 (and later) devices.
Remarks
This API behaves in accordance to the native Android packageManager.hasSystemFeature() API.
Platform Availability
- Android
voltmx.localAuthentication.getBiometryType
This API differentiates whether a device supports either the Touch ID or Face ID feature. The voltmx.localAuthentication.getBiometryType API is available from iOS 11.
Syntax
voltmx.localAuthentication.getBiometryType();
Example
function getBiometryTypeOfDevice() {
var promptMessage = "Sign in with ";
switch (voltmx.localAuthentication.getBiometryType()) {
case constants.BIOMETRY_TYPE_NONE:
// Handle the case if the device doesn't support any biometryType
break;
case constants.BIOMETRY_TYPE_TOUCHID:
promptMessage += "TouchID";
break;
case constants.BIOMETRY_TYPE_FACEID:
promptMessage += "FaceID";
break;
case constants.BIOMETRY_TYPE_UNDEFINED:
// Handle the case if the device is not a iOS11 device or later
break;
}
}
Return Values
| Return Value | Description |
|---|---|
| constants.BIOMETRY_TYPE_NONE | If there is no biometric authentication in the device. |
| constants.BIOMETRY_TYPE_TOUCHID | If the device supports Touch ID authentication. |
| constants.BIOMETRY_TYPE_FACEID | If the device supports Face ID authentication. |
| constants.BIOMETRY_TYPE_UNDEFINED | If this API is called on the device with OS earlier than iOS11. |
Remarks
Face ID is the new biometric authentication that Apple has introduced with iPhoneX. This API will help to customize the prompt message in voltmx.localAuthentication.authenticate. Depending on the type of authentication available, the prompt message is Sign in with FaceID or Sign in with TouchID.
Platform Availability
- iOS
voltmx.localAuthentication.cancelAuthentication
The API cancels the current authentication process.
Note: This API won't work if the deviceCredentialAllowed key in the authenticate() is set to true.
Syntax
voltmx.localAuthentication.cancelAuthentication();
Example
var cancelButton = voltmx.ui.Button({
onClick: btnOnClick
});
function btnOnClick() {
voltmx.localAuthentication.cancelAuthentication()
}
Return Values
| Return Value | Description |
|---|---|
| status | The 5004 status code is returned indicating the authentication is canceled. |
Remarks
The API is available only for the Android platform.
Platform Availability
- Android
voltmx.localAuthentication.getStatusForAuthenticationMode
The API returns the usability status of the authentication.
Note: For information about how to detect whether a device supports either the Touch ID or Face ID biometrics, refer the getBiometryType API.
Syntax
voltmx.localAuthentication.getStatusForAuthenticationMode(
authenticationMode);
Input Parameters
| Parameter | Description |
|---|---|
| authenticationMode | Specifies the authentication mode for which the status is requested. The data type is constant. For the authentication modes, see Authentication Modes. |
Example
function isAuthUsingTouchSupported() {
var status = voltmx.localAuthentication.getStatusForAuthenticationMode(constants.LOCAL_AUTHENTICATION_MODE_TOUCH_ID);
if (status == 5000) {
voltmx.ui.Alert({
message: "AUTHENTICATION BY TOUCHID SUPPORTED",
alertType: constants.ALERT_TYPE_INFO,
yesLabel: "Close"
}, {});
}
else {
var msg = "TOUCHID AUTHENTICATION RETURNED THE STATUS ::" + status;
voltmx.ui.Alert({
message: status,
alertType: constants.ALERT_TYPE_INFO,
yesLabel: "Close"
}, {});
}
}
Return Values
| Return Value | Description |
|---|---|
| status | A status code is returned indicating the usability status of authentication. For status codes, see the Status Codes section. |
Remarks
Using the API, you can verify whether local authentication is supported on the device.
Even when the getStatusForAuthenticationMode(constants.LOCAL_AUTHENTICATION_MODE_BIOMETRICS) API returns a 5005 status code (biometrics not set on the device), you can display a System Authentication prompt with either PIN, PATTERN, or PASSWORD by following these steps:
- Check if device credentials are configured for the device by invoking the
getStatusForAuthenticationMode(constants.LOCAL_AUTHENTICATION_MODE_DEVICE_CREDENTIALS)API.- If the credentials are configured, invoke the
[authenticate](#authenticate)API with thedeviceCredentialAllowedparameter set to True.
Platform Availability
- iOS
- Android
voltmx.localAuthentication.requestBiometricsEnroll
When biometrics are not enrolled on the device, and you invoke the authenticate() API, the 5007 (Authentication does not start because biometrics are not enrolled on the device) error code is returned. In such cases, developers can use the requestBiometricsEnroll API to direct app users to the device settings page, where they can enroll for biometrics and setup device credentials such as PIN/Pattern/Password, if necessary.
Syntax
voltmx.localAuthentication.requestBiometricsEnroll(statusCallback,configMap);
Input Parameters
| Parameter | Description |
|---|---|
| statusCallBack (status, message, info) [function] |
A callback function that conveys the status of the authentication with an appropriate status code. The API returns one of the following status codes:
|
| configMap [dictionary] |
Specifies the configuration dictionary for the API. The configMap parameter uses the following keys:
NOTE:
|
Example
resultCallback: function(info) {
alert("status code : "+ info.status);
},
enrommBiometric : function(){
var configMap = {
"authenticators": [voltmx.localAuthentication.BIOMETRIC_WEAK, voltmx.localAuthentication DEVICE_CREDENTIAL],
"callback" : this.resultCallback
};
voltmx.localAuthentication.enrollBiometrics(configMap);
}
Return Values
None
API Behavior
Based on the authenticator specified in the configMap parameter, and the configuration status of device credentials, the behavior of the API varies as follows:
| Input Authenticator (voltmx.localAuthentication.xxx) | Output Behavior when Device Credentials are not set | Output Behavior when Device Credentials are already set |
|---|---|---|
| [DEVICE_CREDENTIAL] | The user is directed to the settings screen to register for device credentials such as PIN, Pattern, or Password.
| The API returns the 5018 status code. |
| [BIOMETRIC_WEAK] | In devices that use Android API levels less than or equal to 27 (<= 27), the API returns the 5019 status code. In devices that use Android API levels greater than or equal to 28 (>=28), the following system prompt appears.
If the device does not support the BIOMETRIC_WEAK authenticator, the API returns the 5019 status code. | In devices that use Android API levels less than or equal to 27 (<= 27), the API returns the 5019 status code. In devices that use Android API levels greater than or equal to 28 (>=28), the user must first authenticate with the current credential (such as PIN, pattern, or password) used on the device. After confirmation, the user is directed to register for biometrics on the device.
If the device does not support the BIOMETRIC_WEAK authenticator, the API returns the 5019 status code. |
| [BIOMETRIC_STRONG] | In devices that use Android API levels less than or equal to 29 (<= 29), the API returns the 5019 status code. In devices that use Android API levels greater than or equal to 30 (>=30), the following system prompt appears.
If the device does not support the BIOMETRIC_STRONG authenticator, the API returns the 5019 status code. | In devices that use Android API levels less than or equal to 29 (<= 29), the API returns the 5019 status code. In devices that use Android API levels greater than or equal to 30 (>=30), the user must first authenticate with the current credential (such as PIN, pattern, or password) used on the device. After confirmation, the user is directed to register for biometrics on the device.
If the device does not support the BIOMETRIC_STRONG authenticator, the API returns the 5019 status code. |
[BIOMETRIC_WEAK, BIOMETRIC_STRONG, DEVICE_CREDENTIAL] NOTE: BIOMETRIC_WEAK is a superset of BIOMETRIC_STRONG and is defined such that BIOMETRIC_STRONG | BIOMETRIC_WEAK == BIOMETRIC_WEAK | In devices that use Android API levels less than or equal to 27 (<= 27), the API only considers the DEVICE_CREDENTIAL authenticator. In devices that use Android API levels greater than or equal to 28 (>=30), the following system prompt appears.
If the device does not support the BIOMETRIC_WEAK or BIOMETRIC_STRONG authenticators, the user is directed to the settings screen to register for device credentials such as PIN, Pattern, or Password.
| The API displays the following message: One of the specified authenticator (DEVICE_CREDENTIAL) is already enrolled. If the device does not support the BIOMETRIC_WEAK or BIOMETRIC_STRONG authenticators, the API returns the 5018 status code. |
[BIOMETRIC_WEAK, BIOMETRIC_STRONG] NOTE: BIOMETRIC_WEAK is a superset of BIOMETRIC_STRONG and is defined such that BIOMETRIC_STRONG | BIOMETRIC_WEAK == BIOMETRIC_WEAK | In devices that use Android API levels less than or equal to 27 (<= 27), the API returns the 5019 status code. In devices that use Android API levels greater than or equal to 28 (>=28), the following system prompt appears.
If the device does not support the BIOMETRIC_WEAK or BIOMETRIC_STRONG authenticators, the user is directed to the settings screen to register for device credentials such as PIN, Pattern, or Password.
| In devices that use Android API levels less than or equal to 27 (<= 27), the API returns the 5019 status code. In devices that use Android API levels greater than or equal to 28 (>=28), the user must first authenticate with the current credential (such as PIN, pattern, or password) used on the device. After confirmation, the user is directed to register for biometrics on the device.
|
| [BIOMETRIC_WEAK, DEVICE_CREDENTIAL] | In devices that use Android API levels less than or equal to 27 (<= 27), the API only considers the DEVICE_CREDENTIAL authenticator. In devices that use Android API levels greater than or equal to 28 (>=28), the following system prompt appears.
If the device does not support the BIOMETRIC_WEAK authenticator, the user is directed to the settings screen to register for device credentials such as PIN, Pattern, or Password.
| The API displays the following message: One of the specified authenticator (DEVICE_CREDENTIAL) is already enrolled. If the device does not support the BIOMETRIC_WEAK or BIOMETRIC_STRONG authenticators, the API returns the 5018 status code. |
| [BIOMETRIC_STRONG, DEVICE_CREDENTIAL] | In devices that use Android API levels less than or equal to 29 (<= 29), the API only considers the DEVICE_CREDENTIAL authenticator. In devices that use Android API levels greater than or equal to 30 (>=30), the following system prompt appears.
If the device does not support the BIOMETRIC_STRONG authenticator, the user is directed to the settings screen to register for device credentials such as PIN, Pattern, or Password.
| The API displays the following message: One of the specified authenticator (DEVICE_CREDENTIAL) is already enrolled. If the device does not support the BIOMETRIC_WEAK or BIOMETRIC_STRONG authenticators, the API returns the 5018 status code. |
NOTE: The screens are only for the purpose of illustration, and may differ from device to device. The screenshots displayed in the table have been captured on an Android emulator that uses Android API level 30.
Platform Availability
- Android
Authentication Modes
Following are the supported constants for authentication mode.
-
constants.LOCAL_AUTHENTICATION_MODE_TOUCH_ID
The same constant can be used for any biometric authentication mode, i.e. Fingerprint(TouchID), FaceID, and Iris.Note: In case of Android, you can use the constant constants.LOCAL_AUTHENTICATION_MODE_BIOMETRICS in place of the constant constants.LOCAL_AUTHENTICATION_MODE_TOUCH_ID. The Biometric constant would support any biometric authentication mode.
-
constants.LOCAL_AUTHENTICATION_MODE_DEVICE_CREDENTIALS
This constant determines whether the device has either PIN, PATTERN, or PASSWORD configured as the authentication mode.Note: This constant is only available for the
getStatusForAuthenticationModeAPI on the Android platform.When the
getStatusForAuthenticationMode(constants.LOCAL_AUTHENTICATION_MODE_DEVICE_CREDENTIALS)API is invoked on a device, it returns one of the following status codes:- 5000: Indicates that a passcode (either PIN, PATTERN, or PASSWORD) is set on the device.
- 5005: Indicates that the passcode is not set on the device.
Authenticators
Authenticators specify an acceptable list of authenticator types that the device supports. Authenticators are of the following three types:
-
voltmx.localAuthentication.BIOMETRIC_STRONG: Authentication by using biometric credentials (such as fingerprint, iris, or face) that satisfy (meets or exceeds) the requirements for the Strong strength level (Class 3) as defined by the Android Compatibility Definition. This is only supported on Android 11 (API level 30, and later) devices.
-
voltmx.localAuthentication.BIOMETRIC_WEAK: Authentication by using biometric credentials (such as fingerprint, iris, or face) that satisfy (meets or exceeds) the requirements for the Weak strength level (Class 2) as defined by the Android Compatibility Definition. This is only supported on Android (API level 28, and later) devices.
NOTE: BIOMETRIC_WEAK is a superset that can imply either BIOMETRIC_WEAK or BIOMETRIC_STRONG. For more information about Biometric classes , refer to Biometric sensors.
-
voltmx.localAuthentication.DEVICE_CREDENTIAL: Authentication by using non-biometric or device credentials, such as PIN, pattern, or password.
For example, if you specify a combination of the BIOMETRIC_WEAK and DEVICE_CREDENTIAL authenticators, devices that support the BIOMETRIC_WEAK authenticator display a system prompt with the biometric and device credential (PIN/PATTERN/PASSWORD) options. In devices that do not support the BIOMETRIC_WEAK authenticator, the system displays only the device credential (PIN/PATTERN/PASSWORD) options, provided that a device credential (PIN/PATTERN/PASSWORD) is configured on the device.
NOTE: In devices that use Android versions prior to Android 11 (API level 30), a few combinations of authenticators are not supported. For example, using only DEVICE_CREDENTIAL is not supported prior to API level 30, and using BIOMETRIC_STRONG with DEVICE_CREDENTIAL is not supported in API level 28 to 29. If you invoke the API with unsupported authenticators, the API returns an appropriate error code.
Status Codes
The following table provides a list of status codes and their descriptions.
| Status Codes | Description |
|---|---|
| 5000 | No Error |
| 5001 | Authentication is not successful because a user fails to provide valid credentials. |
| 5002 | Authentication is canceled by a user. The following are the examples for different OS. In case of IOS, when a user taps Cancel in the dialog box. In case of Android, when a user presses the device back button while the system UI is displayed. |
| 5003 | Authentication is canceled. iOS: Authentication is canceled because the user tapped the fallback button (Enter Password). Android: Authentication is canceled because the user tapped the negative button. |
| 5004 | Authentication is canceled by system. |
| 5005 | Authentication does not start because the passcode is not set on the device. |
| 5006 | Authentication does not start because biometrics are not available on the device. |
| 5007 | Authentication does not start because biometrics are not enrolled on the device. |
| 5008 | Authentication does not start because the target device's OS does not support local authentication with biometrics. |
| 5009 | Authentication was not successful because there were too many failed user attempts for authentication, and the feature has now been locked. In case of Android, this occurs after 5 failed attempts, and lasts for 30 seconds. |
| 5010 | Error state returned when the current request has been running too long. Applicable only for Android platform. |
| 5011 | The operation was cancelled because 5009 occurred too many times. Authentication is disabled until the user unlocks with strong authentication (PIN/Pattern/Password). Applicable only for Android platform. |
_Note:
Applicable for the Android OS and Devices
Android supports fingerprint, Face ID, and Iris modes of biometric authentication. Availability of the authentication is subject to the support provided by the device. Fingerprint is supported from Android 6 onwards. Face ID and Iris modes are supported from Android 10 onwards.
To support different modes of authentication, a developer need not make any changes to the API configuration. If the device supports multiple biometrics, the developer can specify a default or preferred method in device settings and the API invocation would launch the user preferred authentication flow.
There is no way to know the biometric modes supported by the device. Only the device user knows the biometric authentication supported by the device.





