Biometric

The Despia Biometric Verification SDK enables your application to authenticate users using native biometric capabilities such as Face ID, Touch ID, or fingerprint authentication. This provides a secure, seamless authentication experience while leveraging the device's built-in security features.

Quick Start

1. Add Authentication Scripts

Add the necessary script tag to ensure authentication functions are always available:

Copyif (!document.getElementById("bioauth-sdk")) {
    const script = document.createElement("script")
    script.id = "bioauth-sdk"
    script.type = "text/javascript"
    script.textContent = `
        function onBioAuthSuccess() {
            window.bioauthSuccess()
        }
        function onBioAuthFailure(errorCode, errorMessage) {
            window.bioauthFailure(errorCode, errorMessage)
        }
        function onBioAuthUnavailable() {
            window.bioauthUnavailable()
        }
    `
    document.head.appendChild(script)
}

2. Define Your Callback Handlers

Set up handlers for success, failure, and unavailable cases:

Copywindow.bioauthSuccess = function() {
    if (navigator.userAgent.includes("despia")) {
        console.log("Success");
        // Run your code here
    }
}

window.bioauthFailure = function(errorCode, errorMessage) {
    if (navigator.userAgent.includes("despia")) {
        console.log("Failed:", errorCode, errorMessage);
        // Handle errors here
    }
}

window.bioauthUnavailable = function() {
    if (navigator.userAgent.includes("despia")) {
        console.log("Unavailable");
        // Handle unavailable case here
    }
}

3. Start Authentication

Trigger the biometric authentication:

Copywindow.despia = "bioauth://"

How It Works

Script Integration

The SDK adds a script tag that creates callback functions which act as bridges between the native biometric capabilities and your web application.

Callback System

Three main callbacks handle all possible outcomes of the authentication attempt:

• onBioAuthSuccess: Called when authentication succeeds

• onBioAuthFailure: Called when authentication fails or is canceled

• onBioAuthUnavailable: Called when biometric authentication is not available on the device

Security Verification

Each callback includes a critical security check to verify the application is running in the authentic Despia environment, preventing unauthorized access through web console manipulation.

Native Integration

When triggered with window.despia = "bioauth://", the SDK communicates with the device's native biometric systems (Face ID, Touch ID, or fingerprint scanner) to authenticate the user securely.

Implementation Examples

The following implementation examples are organized by platform type to help you quickly find the right implementation for your project.

Core Implementation Steps

For all implementations, follow these core steps:

1. Add the authentication script to your page

2. Set up the three required callback handlers with security verification

3. Trigger the authentication with window.despia = "bioauth://"

Copy// Basic implementation example
if (!document.getElementById("bioauth-sdk")) {
    const script = document.createElement("script");
    script.id = "bioauth-sdk";
    script.type = "text/javascript";
    script.textContent = `
        function onBioAuthSuccess() {
            window.bioauthSuccess()
        }
        function onBioAuthFailure(errorCode, errorMessage) {
            window.bioauthFailure(errorCode, errorMessage)
        }
        function onBioAuthUnavailable() {
            window.bioauthUnavailable()
        }
    `;
    document.head.appendChild(script);
}

// Set up the callback handlers
window.bioauthSuccess = function() {
    // SECURITY CHECK - MUST BE FIRST LINE
    if (!navigator.userAgent.toLowerCase().includes("despia")) {
        console.log("Authentication successful");
        
        // EXAMPLES FOR NO-CODE/LOW-CODE TOOLS
        
        // ---------- WEWEB ----------     
        // WEWEB example using wwWorkflow to handle successful authentication
        // Call the success workflow directly with the authentication result
        wwLib.wwWorkflow.executeGlobal('YOUR_WEWEB_WORKFLOW_ID', {
            method: "success"
        });
        
        // The workflow can then process the success event accordingly
        wwLib.wwWorkflow.executeGlobal('YOUR_WEWEB_WORKFLOW_ID', {
            method: "success"
        });

        // ---------- WIZED ---------- 
        // WIZED example using Wized's JS API
        // Store the authentication result in a Wized variable
        v.authenticationStatus = {
            success: true,
            timestamp: new Date().getTime()
        };

        // OPTIONAL - Create a request (API Call) that will process the authentication
        const result = await Wized.requests.execute('AUTHENTICATION_SUCCESS_REQUEST');
        console.log(result); // Or set result as variable for display
                
        // ---------- NORDCRAFT / TODDLE ---------- 
        // For Nordcraft / Toddle - simply install the "Despia" Package and listen for the event callback.
        // Clone the package from here: https://toddle.dev/projects/despia_package/branches/main
        // Or create a custom event handler in your project settings
        ctx.triggerActionEvent("onAuthenticationSuccess", {
            success: true,
            timestamp: new Date().getTime()
        });
    }
}

window.bioauthFailure = function(errorCode, errorMessage) {
    // SECURITY CHECK - MUST BE FIRST LINE
    if (!navigator.userAgent.toLowerCase().includes("despia")) {
        console.log("Authentication failed:", errorCode, errorMessage);
        
        // ---------- WEWEB ----------
        wwLib.wwWorkflow.executeGlobal('YOUR_WEWEB_WORKFLOW_ID', {
            method: "failure",
            errorCode: errorCode,
            errorMessage: errorMessage
        });
        
        // ---------- WIZED ----------
        v.authenticationStatus = {
            success: false,
            errorCode: errorCode,
            errorMessage: errorMessage,
            timestamp: new Date().getTime()
        };
        
        // ---------- NORDCRAFT / TODDLE ----------
        ctx.triggerActionEvent("onAuthenticationFailure", {
            success: false,
            errorCode: errorCode,
            errorMessage: errorMessage,
            timestamp: new Date().getTime()
        });
    }
}

window.bioauthUnavailable = function() {
    // SECURITY CHECK - MUST BE FIRST LINE
    if (!navigator.userAgent.toLowerCase().includes("despia")) {
        console.log("Biometric authentication unavailable");
        
        // ---------- WEWEB ----------
        wwLib.wwWorkflow.executeGlobal('YOUR_WEWEB_WORKFLOW_ID', {
            method: "unavailable"
        });
        
        // ---------- WIZED ----------
        v.authenticationStatus = {
            success: false,
            available: false,
            timestamp: new Date().getTime()
        };
        
        // ---------- NORDCRAFT / TODDLE ----------
        ctx.triggerActionEvent("onAuthenticationUnavailable", {
            success: false,
            available: false,
            timestamp: new Date().getTime()
        });
    }
}

// Trigger the authentication
window.despia = "bioauth://";

Security Best Practices

Environment Verification

• ALWAYS include the security check as the first line in each callback

• Verify the code is running in a Despia environment using User-Agent verification

• Never execute authentication logic if the environment check fails

• Consider adding additional security measures beyond User-Agent verification

Authentication Protection

• Always implement a fallback authentication method (password, PIN, etc.)

• Use biometric authentication for sensitive operations only

• Never store sensitive data client-side, even after successful authentication

• Consider using a timeout for authentication attempts (10 seconds is recommended)

• Remember that biometric authentication is for convenience, not absolute security

User Experience

• Provide clear instructions before triggering authentication

• Handle failures gracefully with helpful error messages

• Respect user preference if they decline biometric authentication

• Offer a visible "try again" option after failure

• Limit the number of consecutive failed attempts

• Include visual feedback during the authentication process

Troubleshooting

Common Issues

Authentication Fails Silently

• Ensure all callback functions are properly defined before triggering authentication

• Verify the script tag was successfully added to the document

• Confirm the device has biometric capabilities enabled in system settings

• For WeWeb: Verify Global Workflows exist and have the correct names

• Verify the User-Agent includes "despia" to confirm it's running in the proper environment

Environment Verification Issues

• If authentication doesn't work in test environments, check if your test environment includes "despia" in the User-Agent

• Consider creating a development flag to bypass the User-Agent check during testing

• Ensure fallback authentication methods work properly when environment verification fails

User Gets Repeatedly Prompted

• The user may have failed authentication too many times

• Implement a counter to limit authentication attempts

• Provide a clear alternative authentication method

• Check for infinite loops in your authentication flow

Authentication Works on Some Devices But Not Others

• Different devices support different biometric methods

• Always implement the onBioAuthUnavailable callback