voltmx.localAuthentication Namespace

The API is used to authenticate the user with configurable system UI.

Note: Call the voltmx.localAuthentication.authenticate API only if the [voltmx.localAuthentication.getStatusForAuthenticationMode](#getStatusForAuthenticationMode) API returns the success status code (5000).

Syntax

voltmx.localAuthentication.authenticate(  
    authenticationMode,  
    statusCallback,  
    configMap);

Input Parameters

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

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

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

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

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

Remarks

The API is available only for the Android platform.

Platform Availability

• Android

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

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

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:

1. Check if device credentials are configured for the device by invoking the getStatusForAuthenticationMode(constants.LOCAL_AUTHENTICATION_MODE_DEVICE_CREDENTIALS) API.
2. If the credentials are configured, invoke the [authenticate](#authenticate) API with the deviceCredentialAllowed parameter set to True.

Platform Availability

• iOS
• 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 getStatusForAuthenticationMode API 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.

Status Codes

The following table provides a list of status codes and their descriptions.

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.