Web-App-Integration

Markdown

Diese Seite beschreibt, wie die Unico-Journeys funktionieren und welche Integrationsmodelle verfügbar sind, um sie in eine Anwendung einzubetten.

Eine Journey ist die Abfolge von Schritten, die der Benutzer durchläuft, um eine Identitätsverifizierung abzuschließen. Zum Beispiel: ein Dokumentfoto aufnehmen und eine Gesichtserfassung (Liveness) durchführen.

Unico verwaltet die gesamte Erfahrung. Der Integrationsaufwand ist minimal: Die Journey wird über CreateProcess erstellt, der Benutzer wird dorthin geleitet, und das Ergebnis wird am Ende empfangen. Alles dazwischen — Bildschirme, Anweisungen, Validierungen — ist bereits von Unico erstellt und wird gepflegt.

Zwei Integrationsmodelle

Jeder Kunde hat unterschiedliche Anforderungen. Unico bietet zwei Modelle an, um den Benutzer zur Journey zu leiten.

Modell	Am besten geeignet für
Direkter Zugriff	Mobile Anwendungen, die bereits WebView verwenden, oder Web-Flows, bei denen die Journey außerhalb der Hauptseite stattfinden kann
Journeys SDK	Webanwendungen, die eine integrierte, nahtlose Erfahrung benötigen und den Benutzer in derselben Umgebung halten

Direkter Zugriff

Der Benutzer wird zu einem von Unico gehosteten Link weitergeleitet, wo die Journey stattfindet. Nach Abschluss wird er zur URL zurückgeleitet, die während der Prozesserstellung definiert wurde (der Parameter callbackUri).

Dies ist der einfachste Ansatz: Er erfordert keine Bibliotheksinstallation und funktioniert gut, wenn die Journey nicht innerhalb der eigenen Seite der Anwendung stattfinden muss. Andererseits führt das Herausnehmen des Benutzers aus der Umgebung des Kunden tendenziell zu mehr Reibung und folglich zu einer höheren Absprungrate.

Nach dem Erstellen eines Prozesses enthält die API-Antwort die URL der von Unico gehosteten Journey. Es gibt zwei gängige Wege, den Benutzer dorthin zu leiten:

• Standard-Redirect. Der Benutzer wird direkt zur Journey-URL weitergeleitet. Nach Abschluss leitet Unico ihn zurück zur callbackUri, die während der Prozesserstellung definiert wurde.
• Neuer Tab mit window.open(). Die Journey wird in einem neuen Browser-Tab geöffnet, wobei der Benutzer in einem separaten Kontext bleibt. In diesem Fall wird empfohlen, eine URL-Änderung zur callbackUri zu überwachen und den Tab zu schließen, sobald der Prozess abgeschlossen ist. Siehe die MDN-Dokumentation für Details zur API.

In mobilen Anwendungen ist es üblich, eine WebView zu verwenden, um die Journey direkt zu öffnen, ohne zusätzliche Weiterleitung. In diesem Fall akzeptiert callbackUri auch einen Deeplink, der es ermöglicht, dass der Abschluss der Journey das Öffnen eines bestimmten Bildschirms in der nativen Anwendung auslöst. Konfigurieren Sie einfach den Deeplink als Rückkehrziel und das Betriebssystem übernimmt die Weiterleitung des Benutzers an die richtige Stelle.

Journeys SDK

Die Journey findet innerhalb der Anwendung selbst statt, ohne den Benutzer aus seinem Kontext herauszunehmen. Das Journeys SDK wird in der Anwendung installiert und verwendet, um die Journey bei Bedarf zu öffnen.

Dies ist der empfohlene Weg für eine stärker integrierte und nahtlose Erfahrung, wobei der Benutzer durchgehend in derselben Umgebung bleibt, was tendenziell Reibung und Absprünge im Flow reduziert.

Unico bietet eine JavaScript-Bibliothek, die mit modernen Browsern kompatibel ist, und es ermöglicht, die Journey mit nur wenigen Zeilen Code in praktisch jede Anwendung zu integrieren.

Kompatibilität

Die Bibliothek ist so konzipiert, dass sie reibungslos in jedes Projekt passt, unabhängig vom verwendeten Stack:

• Jede Webanwendung. Im UMD-Format verteilt, funktioniert sie beim Import über moderne Bundler (wie webpack oder Vite). Kompatibel mit jedem Framework (React, Angular, Vue) oder reinem JavaScript.
• Moderne Browser. Die Bibliothek enthält bereits die notwendigen Polyfills für Funktionen wie Promises und async/await, was die Kompatibilität auch auf ältere Browserversionen erweitert.
• Standard-Web-APIs. Die Journey läuft auf nativen Browser-Funktionen, ohne Abhängigkeit von Plugins oder externen Bibliotheken im Projekt.

Wie das SDK intern funktioniert

Wenn eine Journey geöffnet wird, fügt das SDK einen iFrame in die Seite ein und übernimmt die Kontrolle über die gesamte visuelle Erfahrung ab diesem Punkt. Die Bildschirme, Skripte und Assets für jeden Schritt laufen innerhalb dieses iFrames, vom Beginn des Benutzers bis zum Abschluss des Prozesses.

Diese architektonische Entscheidung ist beabsichtigt: Die iFrame-Isolation stellt sicher, dass die Unico-Journey nicht mit den Stilen oder dem Verhalten der Anwendung interferiert. Kein Skript dringt in den externen Kontext, keine CSS-Regel kollidiert mit den eigenen Stilen der Anwendung. Das Ergebnis ist eine konsistente Erfahrung für den Endbenutzer und minimale Auswirkungen auf das Produkt des Kunden.

Da Unico für die Erstellung und Verwaltung des iFrames verantwortlich ist, werden Journey-Verbesserungen — ob bei Leistung, Erfahrung oder Validierung — automatisch an alle Benutzer geliefert, ohne dass Änderungen in der integrierten Anwendung erforderlich sind. Die Integration wird immer mit den besten verfügbaren Optimierungen laufen, ohne dass jedes Plattform-Update nachverfolgt oder darauf reagiert werden muss.

Erste Schritte

Schritt 1 — Installation

Das Paket idpay-b2b-sdk wird zwischen IDPay-Zahlungs-Journeys und Identitätsverifizierungs-Journeys geteilt. Für Identitäts-Anwendungsfälle importieren Sie die Klasse ByUnicoSDK wie in den folgenden Schritten gezeigt.

  npm install idpay-b2b-sdk

Die empfohlene Methode zur Installation des Journeys SDK ist über einen Paketmanager wie npm oder yarn, aus dem auf der npm registry verfügbaren Paket. Neben der Vereinfachung von Installation und Abhängigkeitsverwaltung bietet dieser Ansatz klare Kontrolle über die verwendete Version und macht es einfach, bei Veröffentlichung einer neuen Version zu aktualisieren.

Das SDK folgt Semantic Versioning (SemVer), was bedeutet, dass Patch- und Minor-Updates keine Breaking Changes einführen. Es ist sicher, das Projekt so zu konfigurieren, dass diese Updates automatisch empfangen werden. Änderungen, die Integrationsanpassungen erfordern könnten, sind Major-Versionen vorbehalten und werden immer mit einem Migrationsleitfaden bereitgestellt.

SDK aktuell halten

Auf der neuesten Version zu bleiben ist aus zwei Gründen besonders wichtig. Der erste ist Sicherheit: Sicherheitspatches werden veröffentlicht, wann immer Schwachstellen identifiziert oder Möglichkeiten zur Stärkung des Kommunikationsprotokolls erkannt werden. Eine veraltete Version zu verwenden bedeutet, diese Korrekturen zu verpassen und den Flow unnötigem Risiko auszusetzen. Der zweite ist Stabilität: Bugfixes werden auf die gleiche Weise verteilt, und ältere Versionen können Verhaltensweisen aufweisen, die in neueren Versionen bereits behoben wurden.

Bevor Sie beginnen, registrieren Sie Ihre Domains beim Unico-Support-Team. Alle Domains müssen HTTPS verwenden.

Schritt 2 — CSP und Permissions-Policy konfigurieren

Wenn Ihre Seite bereits Content-Security-Policy- oder Permissions-Policy-Header sendet, fügen Sie die folgenden Direktiven hinzu, damit das iFrame, die Skripte und der Kamerazugriff des SDK korrekt funktionieren.

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");

Information

Wenn Ihre Seite keine CSP- oder Permissions-Policy-Header sendet, können Sie diesen Schritt überspringen — der Browser wendet standardmäßig keine Einschränkungen an.

Schritt 3 — init(options) aufrufen

Initialisiert das SDK und lädt die für den korrekten Betrieb der Journey erforderlichen Skripte vor, was eine flüssigere Erfahrung für den Endbenutzer schafft. Rufen Sie dies so früh wie möglich im Flow auf.

Parameter	Erforderlich	Beschreibung
token	Ja	Prozess-Token, das von der Create Process API zurückgegeben wurde
env	Nein	Auf 'uat' setzen, nur für Testumgebungen

import { ByUnicoSDK } from 'idpay-b2b-sdk';

ByUnicoSDK.init({
  token,
  // env: 'uat' // only for test environments
});

Schritt 4 — open(options) aufrufen

Zeigt den iFrame an und startet die Journey für den Benutzer. Ab diesem Punkt geschieht alles automatisch innerhalb des iFrames, ohne dass ein Zwischenschritt verwaltet werden muss.

Parameter	Erforderlich	Beschreibung
transactionId	Ja	Prozess-ID, die von der Create Process API zurückgegeben wurde
token	Ja	Prozess-Token, das von der Create Process API zurückgegeben wurde
onFinish	Ja	Callback, der ausgeführt wird, wenn die Journey endet oder geschlossen wird
onWidgetVisibilityChange	Nein	Callback, der ausgeführt wird, wenn sich der Sichtbarkeitsstatus des Widgets ändert

Die nächste Interaktion mit der Anwendung erfolgt, wenn die Journey endet, unabhängig davon, ob der Benutzer sie abgeschlossen oder geschlossen hat. Zu diesem Zeitpunkt ruft das SDK den onFinish-Callback auf, der als Parameter in open übergeben wurde. Von dort aus kann die Anwendung die getProcess-API aufrufen, um das Ergebnis zu prüfen, oder auf eine Webhook-Benachrichtigung warten, wenn ein asynchroner Ansatz bevorzugt wird.

Zusätzlich zur Abfrage des Ergebnisses wird empfohlen, onFinish zu verwenden, um den Frontend-Status der Anwendung zu verwalten:

• Schleifen vermeiden. Die sofortige und unnötige Neuerstellung von Prozessen verhindern, falls der Benutzer den Flow direkt nach Ende der Journey erneut auslöst.
• Flow-Management. Sicherstellen, dass der Benutzer zum nächsten Schritt der Anwendung geleitet wird und eine Sackgasse nach dem Schließen der Journey vermieden wird.

Warnung

Der onFinish-Callback signalisiert, dass der Benutzer die Journey abgeschlossen hat, garantiert aber keine Genehmigung. Der Prozess kann mit einem Fehler bei einer der Unico-Validierungsregeln geendet haben. Die Abfrage über getProcess oder der Empfang der Webhook-Benachrichtigung ist nicht optional: Dies sind die einzigen Quellen des tatsächlichen Ergebnisses, und das Verhalten der Anwendung muss darauf basieren. onFinish darf nicht isoliert verwendet werden, um zu bestimmen, ob ein Benutzer genehmigt wurde.

Der onFinish-Callback erhält ein Objekt, das beschreibt, wie die Journey endete:

Feld	Typ	Beschreibung
type	string	Wie die Journey endete: 'FINISH' (abgeschlossen) oder 'CLOSE' (Benutzer hat vor Abschluss geschlossen)
transaction	object | undefined	Vorhanden, wenn type 'FINISH' ist; undefined, wenn type 'CLOSE' ist
transaction.id	string	Prozess-Identifikator (gleich wie übergebene transactionId)
transaction.redirectUrl	string	URL zur Weiterleitung des Benutzers nach der Journey

Die Behandlung des onWidgetVisibilityChange-Callbacks ist optional und möglicherweise nicht relevant für Ihren Anwendungsfall. Er wird aufgerufen, wenn sich der Sichtbarkeitsstatus des Widgets ändert, und ist nur in einem bestimmten Szenario nützlich: Einige Journeys zeigen einen transparenten Hintergrund an, wobei die Anwendungsseite hinter der Erfahrung sichtbar bleibt. Anwendungen, die während des Verifizierungsflows ein benutzerdefiniertes Modal anzeigen (z.B. als Teil einer Orchestrierung über mehrere KYC-Anbieter), könnten dieses Modal hinter dem Unico-Widget anzeigen, was die visuelle Erfahrung verschlechtert. In diesem Fall ermöglicht der Callback der Anwendung, zusätzliche visuelle Elemente zu unterdrücken, während die Unico-Journey aktiv ist, und sie nach deren Ende wiederherzustellen. Wenn Ihre Anwendung keine UI hat, die das Widget überlagern könnte, können Sie ihn bedenkenlos weglassen.

ByUnicoSDK.open({
  transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  onFinish: ({ transaction, type }) => {
    if (type === 'FINISH') {
      // Journey completed (transaction = { id, redirectUrl }) — continue your flow here.
    }
    // type === 'CLOSE' → user closed before finishing;
  },
  // Optional: only needed if your app shows UI that could overlap the widget.
  onWidgetVisibilityChange: (visible) => {
    // suppress or restore your modal based on widget visibility
  },
});

// To close the SDK explicitly at any point:
ByUnicoSDK.close();

Das nachfolgende Sequenzdiagramm zeigt, wie das SDK und das API-Ergebnis verwendet werden, um den iFrame zu konfigurieren:

Beispielanwendungen

Sprache / Framework	Beschreibung	Repository
Angular	PoC in Angular, die das Journeys SDK implementiert	GitHub — unico-cbu-poc-angular
JS Vanilla	PoC in JS Vanilla, die das Journeys SDK implementiert	GitHub — unico-cbu-poc-js
React	PoC in React, die das Journeys SDK implementiert	GitHub — unico-cbu-poc-react
Vue JS	PoC in Vue JS, die das Journeys SDK implementiert	GitHub — unico-cbu-poc-vuejs

Sicherheit

Die Sicherheit in diesem Modell ist in Schichten aufgebaut, beginnend mit dem Kommunikationsprotokoll zwischen dem SDK und der Anwendung, die innerhalb des iFrames läuft.

Wenn die Journey geladen wird, führen beide Parteien einen Handshake durch, um die Kommunikation aufzubauen. In diesem Prozess validiert die Unico-Anwendung den Ursprung der Dateninjektionsnachricht, die über postMessage empfangen wird, gegen eine geschlossene Liste autorisierter Domains, segmentiert nach Umgebung (UAT und PROD). Nachrichten von nicht genehmigten Ursprüngen werden sofort verworfen, was verhindert, dass die Journey in nicht autorisierte Seiten eingebettet wird, und die Angriffsfläche für Schwachstellen wie Clickjacking eliminiert.

Zusätzlich zur Ursprungsvalidierung wird der Flow nur mit einem gültigen Transaktions-Token fortgesetzt: einem Einmal-JWT, das vom Unico-Backend ausgestellt und signiert wurde. Dies stellt sicher, dass selbst ein autorisierter Ursprung nicht mit einem abgelaufenen, wiederverwendeten oder gefälschten Token arbeiten kann.

Nach dem Handshake wird das Token in den iFrame injiziert und es fließen keine sensiblen Informationen zwischen den beiden Parteien. Die gesamte verbleibende Kommunikation dient nur der Schnittstellensteuerung — Öffnen, Schließen und Bildschirmübergänge — und verhindert, dass Prozessdaten während der Journey abgefangen oder preisgegeben werden.

Die iFrame-Isolation schützt auch die Integrität der Unico-Skripte zur Laufzeit. Da der Code in einem vom Seitenkontext getrennten Kontext läuft, kann er nicht von externen Skripten aufgerufen oder modifiziert werden, was sicherstellt, dass die Journey genau wie erstellt ausgeführt wird, ohne Eingriffe.

CSP und Permissions-Policy

Wenn Ihre Seite Content-Security-Policy- oder Permissions-Policy-Header sendet, stellen Sie sicher, dass die folgenden Direktiven vorhanden sind, damit das iFrame, die Skripte und der Kamerazugriff des SDK korrekt funktionieren.

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");

Wenn Ihre Seite diese Header nicht sendet, wendet der Browser standardmäßig keine Einschränkungen an und es ist keine Konfiguration erforderlich.

SDK-spezifische Fehlerbehebung

Dieser Abschnitt behandelt die häufigsten Probleme, die während der Integration auftreten, und die empfohlenen Methoden zur Untersuchung.

Unerwartetes Verhalten oder unterbrochener Flow

Überprüfen Sie, ob ein Anwendungsskript den iFrame direkt im DOM manipuliert. Das SDK erstellt und verwaltet den iFrame im body der Seite, und jede externe Änderung — ob am Scope, an der Positionierung oder an Attributen — kann den Lebenszyklus der Journey beeinträchtigen und unvorhersehbares Verhalten verursachen.

Visuelle Erfahrung anders als erwartet

Überprüfen Sie, ob ein globales Stylesheet der Anwendung Eigenschaften innerhalb des iFrames überschreibt. Das SDK erstellt den iFrame und alle seine internen Elemente mit dynamischen IDs und mit unico präfixierten Klassen, was das Risiko von Konflikten durch ID- oder Klassen-Selektoren erheblich reduziert. Dennoch können breite CSS-Regeln — wie Tag-Selektoren — Elemente innerhalb des iFrames erreichen und die dem Benutzer gelieferte visuelle Erfahrung verändern.

SDK-Bibliotheksdateien direkt modifiziert

Überprüfen Sie, ob eine Bibliotheksdatei außerhalb des Paketmanagers modifiziert wurde. Die Bibliothek muss ausschließlich über npm oder yarn verwaltet werden, ohne direkte Bearbeitungen an installierten Dateien. Manuelle Änderungen können anomales Verhalten erzeugen, das schwer reproduzierbar ist, und verhindern, dass der Unico-Support Hilfe leisten kann.

Halten Sie DevTools während Capture-Tests nicht geöffnet

Die Unico-Anwendung verwendet das Capture SDK (unico-webframe) für die Gesichtserfassung, das geöffnete DevTools als potenzielles Betrugssignal erkennt und die Übermittlung blockiert. Schließen Sie DevTools, bevor Sie End-to-End-Capture-Tests durchführen.

Nicht unterstützte Integrationen

Die in dieser Dokumentation beschriebenen Modelle — direkter Zugriff und Journeys SDK — sind die einzigen offiziell von Unico unterstützten Integrationsansätze. Integrationen, die von diesen Standards abweichen, können zu unerwartetem Verhalten, Sicherheitsflow-Fehlern und Journey-Unterbrechungen führen und werden nicht vom Unico-Support abgedeckt.

Beispiele für nicht unterstützte Ansätze:

• Einbettung des SDK in eine WebView in mobilen Anwendungen. In diesen Fällen ist der korrekte Ansatz die Verwendung des Modells direkter Zugriff, wobei der Journey-Link direkt in der WebView ohne Einbeziehung des Journeys SDK geöffnet wird.
• Direktes Laden des iFrames über ein <iframe>-HTML-Tag, ohne das Journeys SDK zu verwenden. Der iFrame ist ein internes Implementierungsdetail des SDK und darf nicht manuell instanziiert werden. Der korrekte Ansatz ist die Verwendung des Journeys SDK, das den iFrame-Lebenszyklus sicher und innerhalb der erwarteten Standards verwaltet.

Bei Zweifeln, ob ein Ansatz dem unterstützten Standard entspricht, konsultieren Sie die Dokumentation oder kontaktieren Sie den Support, bevor Sie mit der Implementierung fortfahren.