iFrame-Integration

FaceGuard direkt per iframe einbetten für volle Kontrolle über Größe und Layout.

Kommunikationsmethode

Die iframe-Integration verwendet postMessage für die gesamte Kommunikation. Events werden per window.postMessage gesendet und über den message-Event-Listener empfangen.

Mobil (Vollbild)

HTML

<div
  id="faceguard-container"
  style="position: fixed; inset: 0; z-index: 9999; background: #0D141A;"
>
  <iframe
    src="https://faceguard.surt.com/intro?token=YOUR_PORTAL_TOKEN"
    allow="camera"
    style="width: 100%; height: 100%; border: none;"
  ></iframe>
</div>

Desktop (Telefonförmiges Modal)

HTML

<div
  id="faceguard-backdrop"
  style="
    position: fixed; inset: 0; z-index: 9999;
    background: rgba(0, 0, 0, 0.6);
    display: flex; align-items: center; justify-content: center;
  "
>
  <div style="
    width: 420px; height: 760px;
    border-radius: 24px; overflow: hidden;
    box-shadow: 0 24px 48px rgba(0, 0, 0, 0.4);
  ">
    <iframe
      src="https://faceguard.surt.com/intro?token=YOUR_PORTAL_TOKEN"
      allow="camera"
      style="width: 100%; height: 100%; border: none;"
    ></iframe>
  </div>
</div>

Desktop (QR-Code)

Für Desktop-Nutzer: Route /qrcode verwenden, um einen QR-Code anzuzeigen, der die Verifizierung auf dem Smartphone öffnet:

HTML

<iframe
  src="https://faceguard.surt.com/qrcode?token=YOUR_PORTAL_TOKEN"
  allow="camera"
  style="width: 420px; height: 760px; border: none; border-radius: 24px;"
></iframe>

Pflichtattribute

Attribut	Zweck
allow="camera"	Gewährt Kamerazugriff innerhalb des iframes

Kamera erforderlich

Das Attribut allow="camera" ist Pflicht. Ohne es blockiert der Browser den Kamerazugriff und FaceGuard sendet { action: 'close', reason: 'error', error: 'camera_insecure_context' }.

Event-Verarbeitung

JavaScript

window.addEventListener('message', (event) => {
  // Origin in Produktion prüfen
  if (event.origin !== 'https://faceguard.surt.com') return;

  const data = event.data;

  if (data.type === 'surt:ready') {
    console.log('FaceGuard geladen');
    return;
  }

  if (data.action === 'close') {
    switch (data.reason) {
      case 'approved':
        console.log('Verifiziert', data.confidence);
        break;
      case 'rejected':
        console.log('Fehlgeschlagen', data.confidence);
        break;
      case 'canceled':
        console.log('Nutzer hat abgebrochen');
        break;
      case 'bypass_active':
        console.log('Bypass aktiv bis', data.bypass_expires_at);
        break;
      case 'no_base_photo':
        console.log('Kein Basisfoto hinterlegt');
        break;
      case 'error':
        // `data.error` ist ein typisierter Code — siehe Kamera-Fehlercodes in der Referenz
        switch (data.error) {
          case 'camera_permission_denied':
            showToast('Bitte erlauben Sie den Kamerazugriff in den Browser-Einstellungen und versuchen Sie es erneut.');
            break;
          case 'camera_unavailable':
            showToast('Auf diesem Gerät wurde keine Kamera erkannt.');
            break;
          case 'camera_in_use':
            showToast('Ihre Kamera wird von einer anderen App oder einem Tab verwendet.');
            break;
          case 'camera_insecure_context':
            // Vermutlich falsch konfigurierter Embed — im Monitoring loggen
            console.error('FaceGuard: Kamera blockiert, prüfen Sie HTTPS und allow="camera".');
            break;
          default:
            console.log('FaceGuard-Fehler:', data.error);
        }
        break;
    }

    // iframe entfernen
    document.getElementById('faceguard-container')?.remove();
  }
});

Event-Referenz

Event	Payload	Beschreibung
Bereit	{ type: 'surt:ready' }	FaceGuard ist geladen und bereit
Genehmigt	{ action: 'close', reason: 'approved', confidence: number }	Gesicht verifiziert (0-100 Score)
Abgelehnt	{ action: 'close', reason: 'rejected', confidence: number }	Gesicht stimmte nicht überein (0-100 Score)
Abgebrochen	{ action: 'close', reason: 'canceled' }	Nutzer hat FaceGuard geschlossen
Bypass	{ action: 'close', reason: 'bypass_active', bypass_expires_at: string }	Kunde hat aktiven Bypass
Kein Basisfoto	{ action: 'close', reason: 'no_base_photo' }	Kein registriertes Foto zum Vergleich
Fehler	{ action: 'close', reason: 'error', error: string }	Etwas ist schiefgelaufen. Der error-Wert ist ein typisierter Code — siehe Kamera-Fehlercodes.

URL-Parameter

Parameter	Beschreibung
token	Portal-JWT (erforderlich)
lang	Sprachüberschreibung: en, es, pt, de (optional)

Größe

FaceGuard ist für 375x812px ausgelegt und skaliert automatisch.

• Mobil: Vollständiges Viewport (100vw x 100vh)
• Desktop: 420x760px empfohlen mit 24px border-radius
• Minimum: 320px Breite

Dunkler Hintergrund

Setzen Sie background: #0D141A auf den iframe-Container, um einen weißen Aufblitz beim Laden zu verhindern.

Sicherheits-Header

Falls Ihre Website Content Security Policy oder Permissions-Policy-Header verwendet:

frame-src https://faceguard.surt.com;
Permissions-Policy: camera=(self "https://faceguard.surt.com")