React Native

Existem dois caminhos de integração. O pacote npm é recomendado.

	Pacote npm	WebView direto
Configuração	npm install	Manual
Gestão de modais	Integrada	Manual
Tipos TypeScript	Incluídos	Não

Pacote npm

Instalação

npm install @surtai/faceguard-rn react-native-webview

cd ios && pod install

Requisitos de plataforma

iOS - adicione ao Info.plist:

Info.plist

<key>NSCameraUsageDescription</key>
<string>O FaceGuard precisa de acesso à câmara para verificação facial</string>

Android - adicione ao AndroidManifest.xml:

AndroidManifest.xml

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

Configuração

FaceGuard.init() e FaceGuard.verify() requerem FaceGuardProvider na raiz da app. FaceGuardView não.

App.tsx

import { FaceGuardProvider } from '@surtai/faceguard-rn';

export default function App() {
  return (
    <FaceGuardProvider>
      {/* resto da app */}
    </FaceGuardProvider>
  );
}

Utilização

Baseado em promessas (requer provider):

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

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 cancelou');
    break;
  case 'error':
    console.log('Erro', result.error);
    break;
}

Baseado em callbacks (requer provider):

const session = FaceGuard.init({
  token: 'PORTAL_TOKEN',
  onSuccess: (r) => console.log('aprovado', r.confidence),
  onFailed:  (r) => console.log('rejeitado', r.confidence),
  onCancel:  ()  => console.log('cancelado'),
  onError:   (e) => console.log('erro', e.message),
});

// fechar antes se necessário
session.destroy();

Componente declarativo (não requer provider):

import { FaceGuardView } from '@surtai/faceguard-rn';
import { Modal } from 'react-native';

<Modal visible={isOpen} onRequestClose={() => setIsOpen(false)}>
  <FaceGuardView
    token="PORTAL_TOKEN"
    style={{ flex: 1 }}
    onSuccess={() => setIsOpen(false)}
    onCancel={() => setIsOpen(false)}
  />
</Modal>

Integração com navegação

React Navigation

import { useNavigation } from '@react-navigation/native';
import { FaceGuard } from '@surtai/faceguard-rn';

function VerifyButton({ token }: { token: string }) {
  const navigation = useNavigation();

  const handleVerify = async () => {
    const result = await FaceGuard.verify({ token });

    if (result.status === 'approved') {
      navigation.replace('Dashboard', { verified: true });
    } else if (result.status === 'rejected') {
      navigation.replace('VerificationFailed');
    } else if (result.status === 'canceled') {
      navigation.goBack();
    }
  };

  return <Button title="Verificar" onPress={handleVerify} />;
}

Opções

Opção	Tipo	Obrigatório	Padrão	Descrição
token	string	Sim		JWT do portal do seu backend
baseUrl	string	Não	https://faceguard.surt.com	Para ambientes que não são produção
lang	string	Não	Predefinição do dispositivo	'en', 'es', 'pt', ou 'de'

Callbacks (FaceGuard.init)

Callback	Payload	Descrição
onReady		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
}

Tentativa única por token

O backend fecha a sessão após a primeira tentativa. Se o utilizador falhar, o backend deve emitir um novo token do portal antes de chamar verify() novamente.

WebView direto

Use isto se quiser controlo total sobre o ciclo de vida do WebView.

npm install react-native-webview

FaceGuardScreen.tsx

import React from 'react';
import { SafeAreaView, StyleSheet } from 'react-native';
import { WebView } from 'react-native-webview';

interface FaceGuardProps {
  token: string;
  onApproved: (confidence: number) => void;
  onRejected: (confidence: number) => void;
  onCanceled: () => void;
  onError: (message: string) => void;
}

export function FaceGuardScreen({
  token, onApproved, onRejected, onCanceled, onError
}: FaceGuardProps) {
  const uri = `https://faceguard.surt.com/intro?token=${encodeURIComponent(token)}`;

  const handleMessage = (event: { nativeEvent: { data: string } }) => {
    try {
      const data = JSON.parse(event.nativeEvent.data);

      if (data.action === 'close') {
        switch (data.reason) {
          case 'approved':
          case 'bypass_active':
            onApproved(data.confidence ?? 0);
            break;
          case 'rejected':
            onRejected(data.confidence ?? 0);
            break;
          case 'canceled':
            onCanceled();
            break;
          case 'error':
          case 'no_base_photo':
            onError(data.error ?? data.reason);
            break;
        }
      }
    } catch {
      // ignorar mensagens não JSON
    }
  };

  return (
    <SafeAreaView style={styles.container}>
      <WebView
        source={{ uri }}
        onMessage={handleMessage}
        mediaPlaybackRequiresUserAction={false}
        allowsInlineMediaPlayback={true}
        mediaCapturePermissionGrantType="grant"
        javaScriptEnabled={true}
        domStorageEnabled={true}
        style={styles.webview}
      />
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, backgroundColor: '#0D141A' },
  webview: { flex: 1 },
});

iOS - adicione ao Info.plist:

Info.plist

<key>NSCameraUsageDescription</key>
<string>O FaceGuard precisa de acesso à câmara para verificação facial</string>

Android - adicione ao AndroidManifest.xml e gira o pedido de permissão:

AndroidManifest.xml

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

Permissão de câmara Android

<WebView
  {/* ...outras props */}
  onPermissionRequest={(request) => {
    if (request.resources.includes('android.webkit.resource.VIDEO_CAPTURE')) {
      request.grant(request.resources);
    }
  }}
/>

Idioma

Adicione &lang=pt (ou es, de) ao URL:

const uri = `https://faceguard.surt.com/intro?token=${token}&lang=pt`;

Fundo escuro

Use sempre backgroundColor: '#0D141A' no contentor para evitar um destello branco enquanto o WebView carrega.