Biometric Auth

Overview

Call fingerprint or face recognition from JavaScript in your web page. Supported on both Android and iOS.

Feature	Android	iOS
Fingerprint auth	✓ BiometricPrompt (Android 7.0+)	✓ Touch ID
Face auth	✓ BiometricPrompt (Android 7.0+)	✓ Face ID

Supported Plan: Standard and above (requires the biometric license feature)

Prerequisites

Android

The biometric permission ships commented out in AndroidManifest.xml. Uncomment it to enable biometric auth.

<uses-permission android:name="android.permission.USE_BIOMETRIC" />

iOS

To use Face ID, add the NSFaceIDUsageDescription key to your Info.plist. The device automatically selects Face ID or Touch ID depending on hardware support.

<key>NSFaceIDUsageDescription</key>
<string>We use Face ID to verify your identity.</string>

Run Biometric Auth

Call unveilyBridge.auth.biometric(cb) to show the system biometric prompt. cb is a callback function-name string that receives the result. Omit it to use the default 'onBiometricResult'.

// Pass an explicit callback name
window.unveilyBridge.auth.biometric("onBiometricResult");

// Or use the default callback (onBiometricResult)
window.unveilyBridge.auth.biometric();

function onBiometricResult(result) {
  if (result.success) {
    proceedWithSecureAction();       // Auth succeeded
    return;
  }
  if (result.cancelled) {
    return;                          // User cancelled
  }
  // Other failure — not enrolled / not supported / plan required, etc. come through error
  console.error("Authentication failed:", result.error);
  showPasswordFallback();
}

The result is delivered as an already-parsed JS object. You do not need to call JSON.parse(). Not-enrolled, unsupported hardware, and insufficient-plan states all surface through the result.error message.

Response Structure

The callback receives one of these three object shapes.

{ "success": true }

{ "success": false, "cancelled": true }

{ "success": false, "error": "..." }

Field	Description
`success`	Whether authentication succeeded (`true` / `false`)
`cancelled`	`true` when the user cancels the prompt
`error`	Failure reason message (not enrolled / not supported / plan required, etc.)

Server Session Integration

A pattern for confirming a server session after biometric auth succeeds.

function onBiometricResult(result) {
  if (result.success) {
    // Send auth completion signal to server
    fetch('/api/auth/biometric-verified', { method: 'POST' })
      .then(() => window.location.href = '/secure-area');
  }
}

app.post('/api/auth/biometric-verified', (req, res) => {
  // Set biometric verified flag on the already-logged-in session
  if (!req.session.userId) {
    return res.status(401).json({ error: 'Not logged in' });
  }
  req.session.biometricVerified = true;
  res.json({ ok: true });
});

[HttpPost("auth/biometric-verified")]
[Authorize]
public IActionResult BiometricVerified()
{
    HttpContext.Session.SetString("BiometricVerified", "true");
    return Ok(new { ok = true });
}

@PostMapping("/api/auth/biometric-verified")
@PreAuthorize("isAuthenticated()")
public ResponseEntity<?> biometricVerified(HttpSession session) {
    session.setAttribute("biometricVerified", true);
    return ResponseEntity.ok(Map.of("ok", true));
}

<?php
session_start();
if (!isset($_SESSION['user_id'])) {
    http_response_code(401);
    exit(json_encode(['error' => 'Not logged in']));
}
$_SESSION['biometric_verified'] = true;
echo json_encode(['ok' => true]);

<%
If Session("user_id") = "" Then
    Response.Status = "401 Unauthorized"
    Response.End
End If
Session("biometric_verified") = True
Response.ContentType = "application/json"
Response.Write "{""ok"": true}"
%>