Biometric Authentication

Overview

There are two ways to implement biometric authentication:

1. JavaScript SDK - For in-app verification at specific points

2. Biometric App Lock - Blocks entire app access until authenticated

Important: Biometric authentication is a security enhancement, not a replacement for proper backend authentication (Supabase, Xano, etc.). Think of it as an additional layer of security on top of your existing authentication system.

Method 1: Biometric App Lock (Recommended for Security)

The simplest and most secure method requires no code setup in WeWeb.

Setup Steps:

1. Open your Despia editor

2. Navigate to Add-ons

3. Enable Biometric App Lock

4. Rebuild your application

This completely blocks app access until the user verifies their biometric credentials or device passcode.

Method 2: JavaScript SDK Implementation

Use this method for specific in-app verification points (e.g., before sensitive actions).

Copy// Attach Global Functions for Callback
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)
}

Copy// Register Window Callback Functions
const wwBiometricWorkflowID = "YOUR_WORKFLOW_ID" // Replace with your actual workflow ID

window.bioauthSuccess = function () {
    if (navigator.userAgent.includes("despia")) {
        wwLib.wwWorkflow.executeGlobal(wwBiometricWorkflowID, {
            "method": "success",
            "errorCode": null,
            "errorMessage": null
        })
    }
}

window.bioauthFailure = function (errorCode, errorMessage) {
    if (navigator.userAgent.includes("despia")) {
        wwLib.wwWorkflow.executeGlobal(wwBiometricWorkflowID, {
            "method": "failure",
            "errorCode": errorCode,
            "errorMessage": errorMessage
        })
    }
}

window.bioauthUnavailable = function () {
    if (navigator.userAgent.includes("despia")) {
        wwLib.wwWorkflow.executeGlobal(wwBiometricWorkflowID, {
            "method": "unavailable",
            "errorCode": null,
            "errorMessage": null
        })
    }
}

Copy// Run Despia Biometric SDK
window.despia = "bioauth://"

Complete Implementation Example

Page Workflow Structure

CopyStart Biometric Despia SDK (On Page Load)
├── Attach Global Functions for Callback
└── Register Window Callback Functions

Global Workflow Structure

CopyDespia Biometric Callback Handler
└── Multi-Option Split (based on method parameter)
    ├── Success → Execute success actions
    ├── Failure → Show error message
    └── Unavailable → Provide fallback

Use Cases

Secure Sections

Protect sensitive areas like customer data or financial information:

Copy// On button click to access leads section
window.despia = "bioauth://"
// Success callback redirects to protected content

Confirm Critical Actions

Require biometric verification before:

• Logging out

• Making transfers

• Deleting data

• Posting content

• Accessing personal information

Session Extension

Use successful biometric authentication to refresh user tokens:

Copy// In success callback
// Call API to refresh token
// Extend session validity by 30 days

Platform Support

iOS

• Full support for Face ID

• Full support for Touch ID

• Fallback to device passcode

Android

• Biometric App Lock: Works on 99% of devices

• JavaScript SDK: Limited support on some devices

• Automatic fallback to device passcode

Security Considerations

Important Security Notes

1. Client-side protection only

   • Prevents casual unauthorized access

   • Tech-savvy users could bypass through browser console

   • Not suitable as sole security measure

2. Backend security required

   • Always implement proper server-side authentication

   • Use this as an additional layer, not a replacement

   • Validate all sensitive operations server-side

3. User agent verification

   • The navigator.userAgent.includes("despia") check ensures code only runs in native app

   • Prevents execution in web browsers

   • Can be spoofed by determined attackers

4. Physical security focus

   • Best for preventing unauthorized access to unlocked devices

   • Protects against someone grabbing an unlocked phone

   • Not protection against remote attacks

Testing Your Implementation

Test Scenarios

1. Successful Authentication

   • User provides correct biometric

   • Verify success callback executes

   • Check that protected content becomes accessible

2. Failed Authentication

   • User provides incorrect biometric

   • Verify failure callback executes

   • Confirm error message displays

3. Cancelled Authentication

   • User cancels biometric prompt

   • Should trigger failure callback

   • Application should remain secure

4. Unavailable Biometric

   • Test on device without biometric support

   • Verify unavailable callback executes

   • Check fallback method works

Testing Steps

1. Deploy your WeWeb application

2. Build in Despia editor

3. Install through TestFlight (iOS) or equivalent (Android)

4. Test each scenario above

5. Verify callbacks work correctly

6. Test on multiple device types

Troubleshooting

Common Issues and Solutions

Summary

Biometric authentication with Despia adds a valuable security layer to your WeWeb mobile applications. While not a replacement for backend security, it significantly improves the user experience and provides protection against casual unauthorized access. Choose between the simple Biometric App Lock for maximum security or the flexible JavaScript SDK for targeted protection of specific features.

Remember: This is a security enhancement, not a security foundation. Always implement proper backend authentication and validation for all sensitive operations.