How to: Prompt for the Device Password

Posted on 23. March 2023 by Jan Bunk

If you're looking for a finished solution that requests a custom password (not the device password) when a user opens the app check out the password protection feature.

Do you want to improve your app's security while still maintaining great usability? Local authentication might be the way to go. This documentation will show you how you can prompt the users of your app to enter their device PIN/Fingerprint/Face ID before accessing parts of your app.

Enabling the feature

Enable the biometrics permission in your permission settings. Otherwise this feature may only work partially (no Face ID) or break in unexpected ways.

Using the JavaScript Function

You might want to check out the executeWhenAppReady() function of our app helper script. It ensures that your website doesn't try to interact with the app before it's ready or when your website is loaded using a regular browser (ReferenceError, function is not defined).


Use this function to prompt the user for authentication.

    try {
        // This message will be displayed to the user along with the prompt.
        let reason = "Please authenticate to access this part of the app";

        // returns a boolean. True if the authentication was successful, false if it failed (e.g. because the user
        // canceled it by pressing the back button).
        let authenticationResult = (await requestLocalAuthentication(reason))["result"];
    catch (e) {
        switch(e) {
            case "NotAvailable":
                // The user has not configured an authentication method on the device.
                // Occurred on Android in this case, difference to PasscodeNotSet is not completely clear.
            case "PasscodeNotSet":
                // The user has not configured a passcode (iOS) or PIN/pattern/password (Android) on the device
            case "LockedOut":
                // Authentication is temporarily locked due to too many attempts.
            case "PermanentlyLockedOut":
                // Authentication is more persistently locked out than with "LockedOut".
                // Strong authentication like PIN/Pattern/Password is required to unlock.