NPM-Paket

Das @surtai/faceguard SDK ist die empfohlene Methode zur Integration von FaceGuard in Web-Anwendungen. Es übernimmt automatisch iframe-Erstellung, Geräteerkennung, Event-Mapping und Cleanup.

npm install @surtai/faceguard

Callback-Stil (FaceGuard.init)

TypeScript

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

const fg = FaceGuard.init({
  token: 'PORTAL_TOKEN',
  onReady: () => console.log('FaceGuard geladen'),
  onSuccess: (result) => {
    console.log('Genehmigt', result.confidence);
    // Zugriff gewähren
  },
  onFailed: (result) => {
    console.log('Abgelehnt', result.confidence);
    // Zugriff verweigern oder erneut versuchen
  },
  onCancel: () => console.log('Nutzer hat geschlossen'),
  onError: (error) => console.log('Fehler', error.message),
});

// Manuell aufräumen falls nötig
fg.destroy();

Async/Await-Stil (FaceGuard.verify)

TypeScript

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

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

switch (result.status) {
  case 'approved':
    console.log('Verifiziert', result.confidence);
    break;
  case 'rejected':
    console.log('Fehlgeschlagen', result.confidence);
    break;
  case 'canceled':
    console.log('Nutzer hat geschlossen');
    break;
  case 'error':
    console.log('Fehler:', result.error);
    break;
}

Optionen

Option	Typ	Erforderlich	Standard	Beschreibung
token	string	Ja		Portal-JWT von Ihrem Backend
baseUrl	string	Nein	https://faceguard.surt.com	Override für Nicht-Produktionsumgebungen
mode	'mobile' | 'desktop'	Nein	Automatisch	Mobilen (Kamera) oder Desktop-Flow (QR) erzwingen
container	HTMLElement	Nein	document.body	DOM-Element zum Einbinden des Overlays
lang	string	Nein	Browser-Standard	'en', 'es', 'pt' oder 'de'

Callbacks (FaceGuard.init)

Callback	Payload	Beschreibung
onReady		FaceGuard-iframe geladen
onSuccess	{ confidence: number }	Verifizierung bestanden (0-100)
onFailed	{ confidence: number }	Verifizierung fehlgeschlagen (0-100)
onCancel		Nutzer hat FaceGuard geschlossen
onError	{ message: string }	Etwas ist schiefgelaufen

Ergebnis (FaceGuard.verify)

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

Geräteerkennung

Das SDK erkennt automatisch Mobil vs. Desktop:

• Mobil / Tablet: Öffnet /intro - Vollbild-Kamera-Flow
• Desktop: Öffnet /qrcode - telefonförmiges Modal mit QR-Code + "Hier verifizieren"

Die Erkennung nutzt Touch-Fähigkeit + Bildschirmgröße + UA-Hints (erkennt iPads im Querformat, Android-Tablets usw.). Mit mode: 'mobile' oder mode: 'desktop' überschreiben falls nötig.

Framework-Beispiele

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 erstellt eigenes 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}>Identität verifizieren</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>

Umgebungen

Umgebung	baseUrl
Produktion	Weglassen (Standard: https://faceguard.surt.com)
QA	'https://qa.faceguard.surt.com'
Staging	'https://staging.faceguard.surt.com'
Lokale Entwicklung	'http://localhost:5173'