React Native

Es gibt zwei Integrationsmöglichkeiten. Das npm-Paket wird empfohlen.

	npm-Paket	Raw WebView
Einrichtung	npm install	Manuell
Modal-Verwaltung	Integriert	Manuell
TypeScript-Typen	Enthalten	Nein

npm-Paket

Installation

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

cd ios && pod install

Plattformanforderungen

iOS - hinzufügen zu Info.plist:

Info.plist

<key>NSCameraUsageDescription</key>
<string>FaceGuard benötigt Kamerazugriff für die Gesichtsverifikation</string>

Android - hinzufügen zu AndroidManifest.xml:

AndroidManifest.xml

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

Einrichtung

FaceGuard.init() und FaceGuard.verify() benötigen FaceGuardProvider an der App-Wurzel. FaceGuardView nicht.

App.tsx

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

export default function App() {
  return (
    <FaceGuardProvider>
      {/* Rest der App */}
    </FaceGuardProvider>
  );
}

Verwendung

Promise-basiert (benötigt Provider):

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

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('Benutzer hat abgebrochen');
    break;
  case 'error':
    console.log('Fehler', result.error);
    break;
}

Callback-basiert (benötigt Provider):

const session = FaceGuard.init({
  token: 'PORTAL_TOKEN',
  onSuccess: (r) => console.log('genehmigt', r.confidence),
  onFailed:  (r) => console.log('abgelehnt', r.confidence),
  onCancel:  ()  => console.log('abgebrochen'),
  onError:   (e) => console.log('fehler', e.message),
});

// frühzeitig schließen falls nötig
session.destroy();

Deklarative Komponente (kein Provider nötig):

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>

Navigation Integration

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="Verifizieren" onPress={handleVerify} />;
}

Optionen

Option	Typ	Erforderlich	Standard	Beschreibung
token	string	Ja		Portal-JWT vom Backend
baseUrl	string	Nein	https://faceguard.surt.com	Für Nicht-Produktionsumgebungen
lang	string	Nein	Gerätestandard	'en', 'es', 'pt', oder 'de'

Callbacks (FaceGuard.init)

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

Ergebnis (FaceGuard.verify)

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

Einmaliger Versuch pro Token

Das Backend schließt die Sitzung nach dem ersten Versuch. Wenn der Benutzer scheitert, muss das Backend einen neuen Portal-Token ausstellen, bevor verify() erneut aufgerufen wird.

Raw WebView

Verwenden Sie dies, wenn Sie die volle Kontrolle über den WebView-Lebenszyklus möchten.

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 {
      // Nicht-JSON-Nachrichten ignorieren
    }
  };

  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 - hinzufügen zu Info.plist:

Info.plist

<key>NSCameraUsageDescription</key>
<string>FaceGuard benötigt Kamerazugriff für die Gesichtsverifikation</string>

Android - hinzufügen zu AndroidManifest.xml und Kameraberechtigungsanfrage verarbeiten:

AndroidManifest.xml

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

Android Kameraberechtigung

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

Sprache

&lang=de (oder es, pt) an die URL anhängen:

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

Dunkler Hintergrund

Verwenden Sie immer backgroundColor: '#0D141A' auf dem Container, um einen weißen Blitz während des WebView-Ladens zu vermeiden.