Triggering Biometric Auth

Last updated: May 22, 2026

The biometric authentication bridge lets your website trigger Face ID or fingerprint verification on demand — not just when navigating to a protected URL, but at any moment your code decides. This is useful for confirming identity before a critical action: submitting a payment, revealing a private field, or deleting account data.

Triggering Authentication

Send this message from your website to open the biometric prompt:

javascript
appilix.postMessage(JSON.stringify({
    type: "biometric_auth_init",
    props: {
        url: "https://example.com/dashboard",
        description: "Confirm your identity to proceed",
        force_biometric_only: false
    }
}));

Parameters

ParameterRequiredDescription
urlNoURL to navigate to after successful authentication. If omitted, the app stays on the current page
descriptionNoMessage shown in the authentication dialog
force_biometric_onlyNoSet to true to accept only biometrics (Face ID/fingerprint), rejecting PIN/pattern/password

Handling the Response

Set up a listener before or immediately after triggering the prompt:

javascript
appilix.onmessage = function(event) {
    const data = JSON.parse(event.data);

    switch (data.response) {
        case 'success':
            // Authentication passed — proceed with the protected action
            break;
        case 'failed':
            // User failed authentication (wrong fingerprint, Face ID mismatch)
            break;
        case 'missing':
            // Device has no biometric hardware or no enrolled biometrics
            break;
        case 'error':
            // Unexpected error during authentication
            break;
    }

    appilix.onmessage = null;
};

Example: Protect a Button Action

javascript
document.querySelector('#delete-account-btn').addEventListener('click', function () {
    if (typeof appilix === 'undefined') {
        // In browser — use a different confirmation method
        return;
    }

    appilix.onmessage = function(event) {
        const data = JSON.parse(event.data);
        if (data.response === 'success') {
            // Proceed with account deletion
            fetch('/api/delete-account', { method: 'POST' });
        }
        appilix.onmessage = null;
    };

    appilix.postMessage(JSON.stringify({
        type: "biometric_auth_init",
        props: {
            description: "Verify your identity to delete your account"
        }
    }));
});
Tip: Always check typeof appilix !== 'undefined' before calling bridge methods so your website degrades gracefully in a regular browser.