Pacote NPM

O SDK @surtai/faceguard é a forma recomendada de integrar o FaceGuard em aplicações web. Gere automaticamente a criação do iframe, deteção do dispositivo, mapeamento de eventos e limpeza.

npm install @surtai/faceguard

Estilo com callbacks (FaceGuard.init)

TypeScript

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

const fg = FaceGuard.init({
  token: 'PORTAL_TOKEN',
  onReady: () => console.log('FaceGuard carregado'),
  onSuccess: (result) => {
    console.log('Aprovado', result.confidence);
    // Conceder acesso
  },
  onFailed: (result) => {
    console.log('Rejeitado', result.confidence);
    // Negar acesso ou tentar novamente
  },
  onCancel: () => console.log('Utilizador fechou'),
  onError: (error) => console.log('Erro', error.message),
});

// Limpar manualmente se necessário
fg.destroy();

Estilo async/await (FaceGuard.verify)

TypeScript

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

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

switch (result.status) {
  case 'approved':
    console.log('Verificado', result.confidence);
    break;
  case 'rejected':
    console.log('Falhado', result.confidence);
    break;
  case 'canceled':
    console.log('Utilizador fechou');
    break;
  case 'error':
    console.log('Erro:', result.error);
    break;
}

Opções

Opção	Tipo	Obrigatório	Padrão	Descrição
token	string	Sim		JWT de portal do seu backend
baseUrl	string	Não	https://faceguard.surt.com	Override para ambientes que não sejam de produção
mode	'mobile' | 'desktop'	Não	Deteção automática	Forçar fluxo móvel (câmara) ou desktop (QR)
container	HTMLElement	Não	document.body	Elemento DOM onde montar o overlay
lang	string	Não	Idioma do browser	'en', 'es', 'pt' ou 'de'

Callbacks (FaceGuard.init)

Callback	Payload	Descrição
onReady		iframe do FaceGuard carregado
onSuccess	{ confidence: number }	Verificação aprovada (0-100)
onFailed	{ confidence: number }	Verificação falhada (0-100)
onCancel		Utilizador fechou o FaceGuard
onError	{ message: string }	Algo correu mal

Resultado (FaceGuard.verify)

interface FaceGuardVerifyResult {
  status: 'approved' | 'rejected' | 'canceled' | 'error';
  confidence?: number;  // 0-100, presente para approved/rejected
  error?: string;       // presente para o estado error
}

Deteção de dispositivo

O SDK deteta automaticamente móvel vs desktop:

• Móvel / Tablet: Abre /intro - fluxo de câmara em ecrã completo
• Desktop: Abre /qrcode - modal em forma de telemóvel com código QR + "Verificar aqui"

A deteção usa capacidade táctil + tamanho de ecrã + UA hints (deteta iPads na horizontal, tablets Android, etc.). Substitua com mode: 'mobile' ou mode: 'desktop' se necessário.

Exemplos por framework

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; // O SDK cria o seu próprio 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}>Verificar identidade</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>

Ambientes

Ambiente	baseUrl
Produção	Omitir (padrão: https://faceguard.surt.com)
QA	'https://qa.faceguard.surt.com'
Staging	'https://staging.faceguard.surt.com'
Dev local	'http://localhost:5173'