NPM Package

The @surtai/faceguard SDK is the recommended way to integrate FaceGuard into web applications. It handles iframe creation, device detection, event mapping, and cleanup automatically.

npm install @surtai/faceguard

Callback Style (FaceGuard.init)

TypeScript

import { FaceGuard } from '@surtai/faceguard';

const fg = FaceGuard.init({
  token: 'PORTAL_TOKEN',
  onReady: () => console.log('FaceGuard loaded'),
  onSuccess: (result) => {
    console.log('Approved', result.confidence);
    // Grant access
  },
  onFailed: (result) => {
    console.log('Rejected', result.confidence);
    // Deny access or retry
  },
  onCancel: () => console.log('User closed'),
  onError: (error) => console.log('Error', error.message),
});

// Clean up manually if needed
fg.destroy();

Async/Await Style (FaceGuard.verify)

TypeScript

import { FaceGuard } from '@surtai/faceguard';

const result = await FaceGuard.verify({ token: 'PORTAL_TOKEN' });

switch (result.status) {
  case 'approved':
    console.log('Verified', result.confidence);
    break;
  case 'rejected':
    console.log('Failed', result.confidence);
    break;
  case 'canceled':
    console.log('User closed');
    break;
  case 'error':
    console.log('Error:', result.error);
    break;
}

Options

Option	Type	Required	Default	Description
token	string	Yes		Portal JWT from your backend
baseUrl	string	No	https://faceguard.surt.com	Override for non-prod environments
mode	'mobile' | 'desktop'	No	Auto-detect	Force mobile (camera) or desktop (QR) flow
container	HTMLElement	No	document.body	DOM element to mount the overlay into
lang	string	No	Browser default	'en', 'es', 'pt', or 'de'

Callbacks (FaceGuard.init)

Callback	Payload	Description
onReady		FaceGuard iframe loaded
onSuccess	{ confidence: number }	Verification passed (0-100)
onFailed	{ confidence: number }	Verification failed (0-100)
onCancel		User closed FaceGuard
onError	{ message: string }	Something went wrong

Result (FaceGuard.verify)

interface FaceGuardVerifyResult {
  status: 'approved' | 'rejected' | 'canceled' | 'error';
  confidence?: number;  // 0-100, present for approved/rejected
  error?: string;       // present for error status
}

Device Detection

The SDK auto-detects mobile vs desktop:

• Mobile / Tablet: Opens /intro - fullscreen camera flow
• Desktop: Opens /qrcode - phone-shaped modal with QR code + "Verify Here"

Detection uses touch capability + screen size + UA hints (catches iPads in landscape, Android tablets, etc.). Override with mode: 'mobile' or mode: 'desktop' if needed.

Framework Examples

React

React

import { useEffect, useRef } from 'react';
import { FaceGuard } from '@surtai/faceguard';

function FaceVerification({ token, onResult }) {
  const fgRef = useRef(null);

  useEffect(() => {
    fgRef.current = FaceGuard.init({
      token,
      onSuccess: (result) => onResult('approved', result.confidence),
      onFailed: (result) => onResult('rejected', result.confidence),
      onCancel: () => onResult('canceled'),
      onError: (error) => onResult('error', error.message),
    });

    return () => fgRef.current?.destroy();
  }, [token]);

  return null; // SDK creates its own overlay
}

Next.js

Next.js

'use client';

import { useCallback } from 'react';
import { FaceGuard } from '@surtai/faceguard';

export function VerifyButton({ token }: { token: string }) {
  const handleVerify = useCallback(async () => {
    const result = await FaceGuard.verify({ token });
    if (result.status === 'approved') {
      window.location.href = '/dashboard';
    }
  }, [token]);

  return <button onClick={handleVerify}>Verify Identity</button>;
}

Vue

Vue

<script setup>
import { onMounted, onUnmounted } from 'vue';
import { FaceGuard } from '@surtai/faceguard';

const props = defineProps(['token']);
const emit = defineEmits(['result']);
let fg = null;

onMounted(() => {
  fg = FaceGuard.init({
    token: props.token,
    onSuccess: (r) => emit('result', { status: 'approved', confidence: r.confidence }),
    onFailed: (r) => emit('result', { status: 'rejected', confidence: r.confidence }),
    onCancel: () => emit('result', { status: 'canceled' }),
  });
});

onUnmounted(() => fg?.destroy());
</script>

Environments

Environment	baseUrl
Production	Omit (default: https://faceguard.surt.com)
QA	'https://qa.faceguard.surt.com'
Staging	'https://staging.faceguard.surt.com'
Local dev	'http://localhost:5173'