Page tree
Skip to end of metadata
Go to start of metadata

This guide explains, usage of fingerprint authentication with Touch ID in Smartface applications will be explained.

Property – canEvaluateFingerPrint

This property returns a boolean value. If device has a fingerprint scanner/Touch ID (if device is available for biometry), it returns true. iPhone 5S and later devices and iPad Air 2 and later devices support Touch ID. For older devices, it returns false. And also for Android it always returns false for now. Android 6.0 Marshmallow supports fingerprint authentication, which is implemented in Smartface, but it will be activated in a future release. Android support is present so that you can start developing your fingerprint authentication apps with a single codebase for iOS and Android.

if (Device.canEvaluateFingerPrint) {
	// here scan fingerprint method can be called
} else {
	// biometry is not available for that device
}

If it returns false, it means device is not available for fingerprint scanning.

Method – scanFingerPrint

This method is used to scan the fingerprint. It is not available for older devices that do not support fingerprint. It takes 4 parameters these are ; "title, subtitle, icon and fallbackText". Title and icon are Android only features and fallbackText is an iOS only feature. The only common one between iOS and Android is the subtitle.These 4 parameters can be used but it is not mandatory to use them all. But for subtitle, the field remains empty if it is not filled. Because it is not allowed to use this method without the subtitle, if an empty string is set for subtitle or even it is not declared at all, an empty field will be shown related to subtitle field. 
An example usage will be as below:

var myButton = new SMF.UI.TextButton({
        left : "15%",
        top : "25%",
      	width : "70%",
        height : "10%",
        text : "Scan fingerPrint"
    });
myButton.onPressed = function () {
    if (Device.canEvaluateFingerPrint) {
        Device.scanFingerPrint({
            title : "myTitle", // Android only, ignored in iOS
            subtitle : "mySubtitle",
            icon : "myicon.png", // Android only, ignored in iOS
            fallbackText : "Enter Password" // iOS only, ignored in Android
        }, function onSuccess(e) {
            // Scan is success
        }, function onError(e) {
            alert("code: " + e.code +
                "\n description: " + e.description);
            if (e.code == "-3") { // -3 is errorCode of fallback
                // a password field can be showed to user
                alert("Fallback called");
            }
        });
    }
}

When pressed on the button created above, Device.scanFingerPrint method will run and, on device it will look like below:

When scanFingerPrint ends successfully, onSuccess does not return any value.But when it fails for some reason, onError returns e.code and e.description values. e.code stands for the error code, and e.description is for the error description.
When fallbackText is provided and when fingerprint scanning is not successful, a new button which has the text as fallbackText, will appear above “Cancel” button as in the screenshot below:

As an example, “Enter password” is used for fallbackText. If it is pressed, error event will be fired with a specific error code which is -3.
In the above example, e.code is checked and if it is equal to -3, that means fallback is called.

Instead of showing an alert, a new password field can be designed in order to enter a defined password to proceed without fingerprint scanning/Touch ID.

Some error cases

  • When the user tries to scan wrong a fingerprint at least 3 times, it returns -1 as e.code and “Application retry limit exceeded” as e.description.
  • When user presses “Cancel”, it returns -2 as e.code and “Canceled by user” as e.description.

          

  • When user presses home button on device, it returns -4 as e.code and “UI canceled by system IOS-1715 - Getting issue details... STATUS as e.description.

          

  • And if the device does not support fingerprint scanning, when you try to run scan method on this device it returns -6 as e.code and “Biometry is not available on this device” as e.description.