Web-Erfassung

Führen Sie die Person im Browser durch die Erfassung, mit dem Token und dem Link, die Human Plugin zurückgibt.

Markdown

Ihr Back-End erstellt den Prozess in Human Plugin mit einem Journey-Flow. Die Antwort 201 enthält drei Werte, die das Front-End benötigt:

Feld	Verwendung
id	Die Prozess-ID von Human Plugin. Das SDK übernimmt sie als transactionId, und Ihr Back-End liest damit das Ergebnis aus
token	Startet die Erfassung im Journeys SDK
link	Die gehostete Erfassungsseite

token und link werden nur vom create zurückgegeben. Übergeben Sie sie in derselben Anfrage an das Front-End oder speichern Sie sie selbst. Siehe Human Token Journey.

Anforderungen

Die Erfassung läuft im Browser und benötigt Zugriff auf die Kamera.

Betriebssystem	Chrome	Firefox	Safari	Samsung Internet	Opera	Edge
Windows	✅	✅	N/A	N/A	❌	❌
macOS	✅	✅	✅	N/A	❌	❌
Android	✅	❌	N/A	✅	❌	❌
iOS	✅	✅	✅	N/A	❌	❌

• Seiten müssen über HTTPS ausgeliefert werden. Die Kamera funktioniert nur in einem sicheren Kontext.
• Das Browsen in der App erfordert Android 8 (API 26) oder iOS 13 oder neuer.
• Browser innerhalb von Social-Media-Apps werden nicht unterstützt.

Modell wählen

Modell	Am besten geeignet für
Gehosteter Link	Die einfachste Einrichtung. Keine Bibliothek: Die Person öffnet den link und kehrt zu Ihrer callbackUri zurück
Journeys SDK	Die Erfassung öffnet sich innerhalb Ihrer Seite, sodass die Person sie nie verlässt

Gehosteter Link

Senden Sie callbackUri in der create-Anfrage. Das ist die Seite, zu der die Person zurückkehrt, wenn die Erfassung endet.

{
  "flow": "humantoken",
  "clientId": "client-a",
  "correlationId": "order-1001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
  "callbackUri": "https://app.example.com/capture/done"
}

Leiten Sie die Person anschließend auf zwei Arten zum link:

• Weiterleitung. Navigieren Sie zum link. Am Ende wird die Person zur callbackUri zurückgeleitet.
• Neuer Tab. Öffnen Sie den link mit window.open(), beobachten Sie, wann der Tab die callbackUri erreicht, und schließen Sie ihn.

Wenn die Person zurück ist, informieren Sie Ihr Back-End, das GET /v1/processes/{id} aufruft.

Journeys SDK

Das SDK öffnet die Erfassung in einem iFrame auf Ihrer Seite. Es funktioniert mit jedem Framework (React, Angular, Vue) oder mit reinem JavaScript.

Bitten Sie vorab den Unico-Support, Ihre Domains zu registrieren. Sie müssen HTTPS verwenden.

1. Installieren

npm install unico-journey-sdk

Das SDK folgt der semantischen Versionierung, daher können Minor- und Patch-Updates bedenkenlos übernommen werden. Halten Sie es aktuell: Sicherheits- und Fehlerkorrekturen erscheinen in neuen Versionen.

2. SDK in Ihren Headern zulassen

Überspringen Sie diesen Schritt, wenn Ihre Seite weder einen Content-Security-Policy- noch einen Permissions-Policy-Header sendet. Andernfalls fügen Sie hinzu:

Content-Security-Policy:

frame-src https://*.unico.io https://*.unico.app;
script-src https://idpay.unico.io;
style-src https://idpay.unico.io;
connect-src https://api.cadastro.unico.app;

Permissions-Policy:

camera=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io"),
geolocation=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io")

3. Initialisieren

Rufen Sie init auf, sobald Sie wissen, dass die Erfassung benötigt wird. Es lädt die Erfassung vor.

import { ByUnicoSDK } from 'unico-journey-sdk';

ByUnicoSDK.init({ token });

4. Erfassung öffnen

Parameter	Erforderlich	Wert
transactionId	Ja	Die id von Human Plugin
token	Ja	Der token aus dem create
onFinish	Ja	Wird aufgerufen, wenn die Erfassung endet oder die Person sie schließt
onWidgetVisibilityChange	Nein	Wird aufgerufen, wenn die Erfassung ein- oder ausgeblendet wird

ByUnicoSDK.open({
  transactionId: id, // the Human Plugin id
  token,
  onFinish: ({ type }) => {
    if (type === 'FINISH') {
      // The capture ended. Ask your back-end to read the outcome.
    }
    // type === 'CLOSE': the person closed it before the end.
  },
  // Optional: hide your own overlays while the capture is visible.
  onWidgetVisibilityChange: (visible) => {},
});

// To close it yourself:
ByUnicoSDK.close();

onFinish erhält:

Feld	Beschreibung
type	'FINISH', wenn die Erfassung beendet wurde, 'CLOSE', wenn die Person sie vorher geschlossen hat
transaction.redirectUrl	Wohin die Person als Nächstes geleitet werden soll. Nur bei 'FINISH' vorhanden

Warnung

onFinish besagt, dass die Erfassung beendet wurde, nicht mit welchem Ergebnis. Das Ergebnis erhalten Sie ausschließlich über GET /v1/processes/{id} in Ihrem Back-End.

Verwenden Sie onFinish auch, um die Person zum nächsten Bildschirm zu führen und um zu vermeiden, dass sofort ein neuer Prozess erstellt wird, wenn sie erneut beginnt.

Fehlerbehebung

• Der Ablauf bricht ab oder verhält sich merkwürdig. Stellen Sie sicher, dass keines Ihrer Skripte den iFrame des SDK im DOM verändert.
• Die Erfassung sieht anders aus. Allgemeine CSS-Regeln, etwa Tag-Selektoren, können den iFrame erreichen. Die eigenen IDs und Klassen des SDK beginnen mit unico.
• Unerwartete Fehler nach einem Update. Installieren Sie das SDK nur über npm oder yarn und bearbeiten Sie niemals seine Dateien.

Testen

Schließen Sie die Entwicklertools des Browsers, bevor Sie eine Erfassung Ende-zu-Ende testen. Geöffnete Entwicklertools blockieren die Übermittlung.

Nicht unterstützte Konfigurationen

• Das SDK in einer mobilen WebView. Öffnen Sie in einer App stattdessen den link. Siehe die Anleitungen für Android, iOS, Ionic, React Native und Flutter.
• Ihr eigener <iframe>, der auf die Erfassung zeigt. Verwenden Sie das SDK, das den iFrame verwaltet.