Web-App-Integration

Markdown

Diese Seite beschreibt, wie die Unico-Journeys funktionieren und welche Integrationsmodelle für die Einbindung in eine Anwendung verfügbar sind.

Eine Journey ist die Abfolge von Schritten, die ein Nutzer durchläuft, um eine Identitätsprüfung abzuschließen. Zum Beispiel: ein Foto des Dokuments aufnehmen und eine Gesichtserfassung (Lebenderkennung) durchführen.

Unico kümmert sich um das gesamte Erlebnis. Der Integrationsaufwand ist minimal: Die Journey wird über CreateProcess erstellt, der Nutzer wird dorthin geleitet, und am Ende wird das Ergebnis empfangen. Alles, was dazwischen passiert (Bildschirme, Anweisungen, Validierungen), ist bereits fertig und wird von Unico gepflegt.

Zwei Integrationsmodelle

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

Modell	Am besten geeignet für
Journeys SDK	Web-Anwendungen, die ein integriertes, nahtloses Erlebnis benötigen und den Nutzer in derselben Umgebung halten
Direktzugriff	Web-Flows, bei denen die Journey außerhalb der Hauptseite stattfinden kann, oder Anwendungen, die bereits eine WebView einbetten. Native Apps sollten das plattformspezifische SDK bevorzugen

Native Apps

Wenn Ihre Anwendung eine native mobile App ist, empfehlen wir, das SDK für die Plattform zu verwenden, auf der sie entwickelt wurde (Android, iOS oder Flutter), anstatt einer Web-Integration.

Journeys SDK

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

Dies ist der empfohlene Weg für ein stärker integriertes und nahtloses Erlebnis, bei dem der Nutzer durchgehend in derselben Umgebung bleibt, was Reibung und Abbrüche im Verlauf des Flows tendenziell reduziert.

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

Kompatibilität

Die Bibliothek ist darauf ausgelegt, sich reibungslos in jedes Projekt einzufügen, unabhängig vom verwendeten Stack:

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

Wie das SDK intern funktioniert

Beim Öffnen einer Journey fügt das SDK einen iFrame in die Seite ein und übernimmt ab diesem Zeitpunkt die Kontrolle über das gesamte visuelle Erlebnis. Die Bildschirme, Skripte und Assets jedes Schritts laufen innerhalb dieses iFrames, vom Moment des Beginns durch den Nutzer bis zum Abschluss des Prozesses.

Diese Architekturentscheidung ist beabsichtigt: Die iFrame-Isolation stellt sicher, dass die Unico-Journey weder die Stile noch das Verhalten der Anwendung beeinträchtigt. Kein Skript dringt in den externen Kontext, keine CSS-Regel kollidiert mit den eigenen Stilen der Anwendung. Das Ergebnis ist ein konsistentes Erlebnis für den Endnutzer und minimale Auswirkungen auf das Produkt des Kunden.

Da Unico für die Erstellung und Verwaltung des iFrames verantwortlich ist, werden Verbesserungen an der Journey (ob bei Leistung, Erlebnis oder Validierung) automatisch an alle Nutzer ausgeliefert, ohne dass Änderungen in der integrierten Anwendung erforderlich sind. Die Integration läuft stets mit den besten verfügbaren Optimierungen, ohne dass jede Weiterentwicklung der Plattform verfolgt oder darauf reagiert werden muss.

Erste Schritte

Schritt 1: Installation

Das Paket unico-journey-sdk wird von den IDPay-Zahlungs-Journeys und den Identitätsprüfungs-Journeys gemeinsam genutzt. Importieren Sie für Identitäts-Anwendungsfälle die Klasse ByUnicoSDK wie in den folgenden Schritten gezeigt.

  npm install unico-journey-sdk

Früher idpay-b2b-sdk

Dieses Paket wurde zuvor als idpay-b2b-sdk veröffentlicht. Es ist dasselbe SDK unter einem neuen Namen und behält dieselbe Versionslinie bei. Nur 2.3.0 und höher sind unter dem neuen Namen verfügbar — siehe die Versionshinweise für die vollständige Historie.

Die empfohlene Methode zur Installation des Journeys SDK ist über einen Paketmanager wie npm oder yarn, aus dem im npm registry verfügbaren Paket. Neben der Vereinfachung von Installation und Abhängigkeitsverwaltung bietet dieser Ansatz klare Kontrolle über die verwendete Version und erleichtert die Aktualisierung, sobald eine neue Version veröffentlicht wird.

Das SDK folgt der semantischen Versionierung (SemVer), das heißt, Patch- und Minor-Updates führen keine Breaking Changes ein. Es ist sicher, das Projekt so zu konfigurieren, dass es diese Updates automatisch erhält. Änderungen, die Anpassungen an der Integration erfordern könnten, sind Major-Versionen vorbehalten und werden stets von einem Migrationsleitfaden begleitet.

Halten Sie das SDK aktuell

Auf der neuesten Version zu bleiben, ist aus zwei Gründen besonders wichtig. Der erste ist Sicherheit: Sicherheitspatches werden veröffentlicht, sobald Schwachstellen identifiziert werden oder sich Gelegenheiten ergeben, das Kommunikationsprotokoll zu stärken. Eine veraltete Version zu verwenden bedeutet, auf diese Korrekturen zu verzichten und den Flow unnötigen Risiken auszusetzen. Der zweite ist Stabilität: Fehlerbehebungen werden auf dieselbe Weise verteilt, und ältere Versionen können Verhaltensweisen aufweisen, die in neueren Releases bereits behoben wurden.

Registrieren Sie vor dem Start Ihre Domains beim Unico-Support-Team. Alle Domains müssen HTTPS verwenden.

Schritt 2: init(options) aufrufen

Initialisiert das SDK und lädt vorab die Skripte, die für das korrekte Funktionieren der Journey erforderlich sind, was ein flüssigeres Erlebnis für den Endnutzer schafft. Rufen Sie dies so früh wie möglich im Flow auf.

Parameter	Erforderlich	Beschreibung
token	Ja	Vom Create-Process-API zurückgegebenes Prozess-Token
env	Nein	Nur für Testumgebungen auf 'uat' setzen

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

ByUnicoSDK.init({
  token,
  // env: 'uat' // nur für Testumgebungen
});

Schritt 3: open(options) aufrufen

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

Parameter	Erforderlich	Beschreibung
transactionId	Ja	Vom Create-Process-API zurückgegebene Prozess-ID
token	Ja	Vom Create-Process-API zurückgegebenes Prozess-Token
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, sei es, weil der Nutzer sie abgeschlossen oder geschlossen hat. Zu diesem Zeitpunkt ruft das SDK den onFinish-Callback auf, der als Parameter in open übergeben wird. Von dort aus kann die Anwendung das getProcess-API aufrufen, um das Ergebnis zu prüfen, oder auf eine Webhook-Benachrichtigung warten, falls ein asynchroner Ansatz bevorzugt wird.

Zusätzlich zum Abfragen des Ergebnisses wird empfohlen, onFinish zu verwenden, um den Frontend-Zustand der Anwendung zu handhaben:

• Schleifen vermeiden. Verhindern Sie die sofortige und unnötige Neuerstellung von Prozessen, falls der Nutzer den Flow direkt nach dem Ende der Journey erneut auslöst.
• Flow-Steuerung. Stellen Sie sicher, dass der Nutzer zum nächsten Schritt der Anwendung geleitet wird, damit er nach dem Schließen der Journey nicht auf einem Bildschirm ohne Ausweg festhängt.

Warnung

Der onFinish-Callback signalisiert, dass der Nutzer die Journey abgeschlossen hat, garantiert aber keine Genehmigung. Der Prozess kann mit einem Fehlschlag bei einer der Unico-Validierungsregeln geendet haben. Die Abfrage über getProcess oder der Empfang der Webhook-Benachrichtigung ist nicht optional: Sie sind die einzigen Quellen des tatsächlichen Ergebnisses, und das Verhalten der Anwendung muss auf ihnen beruhen. onFinish darf nicht isoliert verwendet werden, um zu bestimmen, ob ein Nutzer 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' (Nutzer hat vor Abschluss geschlossen)
transaction	object | undefined	Vorhanden, wenn type 'FINISH' ist; undefined, wenn type 'CLOSE' ist
transaction.id	string	Prozesskennung (dieselbe wie die übergebene transactionId)
transaction.​redirectUrl	string	URL, um den Nutzer nach der Journey weiterzuleiten

Das Behandeln des onWidgetVisibilityChange-Callbacks ist optional und für Ihren Anwendungsfall möglicherweise nicht relevant. Er wird immer dann aufgerufen, wenn sich der Sichtbarkeitsstatus des Widgets ändert, und ist nur in einem bestimmten Szenario nützlich: Manche Journeys zeigen einen transparenten Hintergrund, wodurch die Seite der Anwendung hinter dem Erlebnis sichtbar bleibt. Anwendungen, die während des Verifizierungsflows ein eigenes Modal anzeigen (zum Beispiel im Rahmen einer Orchestrierung über mehrere KYC-Anbieter), zeigen dieses Modal möglicherweise hinter dem Unico-Widget an, was das visuelle Erlebnis beeinträchtigt. In diesem Fall ermöglicht der Callback der Anwendung, alle zusätzlichen visuellen Elemente zu unterdrücken, solange 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 abgeschlossen (transaction = { id, redirectUrl }): Setzen Sie hier Ihren Flow fort.
    }
    // type === 'CLOSE' → Nutzer hat vor Abschluss geschlossen;
  },
  // Optional: nur nötig, wenn Ihre Anwendung UI anzeigt, die das Widget überlagern könnte.
  onWidgetVisibilityChange: (visible) => {
    // unterdrücken oder stellen Sie Ihr Modal je nach Widget-Sichtbarkeit wieder her
  },
});

// Um das SDK jederzeit explizit zu schließen:
ByUnicoSDK.close();

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

Referenz-App

Sprache / Framework	Beschreibung	Repository
Node.js (Express)	Referenz-App in Node.js, die den vollständigen User-Journey-Flow mit dem Journeys SDK implementiert	GitHub — reference-apps/web

Sicherheit

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

Beim Laden der Journey führen beide Seiten einen Handshake durch, um die Kommunikation aufzubauen. Dabei validiert die Unico-Anwendung den Ursprung der über postMessage empfangenen Dateninjektionsnachricht gegen eine geschlossene Liste autorisierter Domains, segmentiert nach Umgebung (UAT und PROD). Nachrichten von nicht zugelassenen 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 beseitigt.

Zusätzlich zur Ursprungsvalidierung wird der Flow nur mit einem gültigen Transaktionstoken fortgesetzt: einem JWT zur einmaligen Verwendung, ausgestellt und signiert vom Unico-Backend. 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 mehr zwischen den beiden Seiten. Die gesamte übrige Kommunikation dient nur der Oberflächensteuerung (Öffnen, Schließen und Bildschirmübergänge) und verhindert, dass Prozessdaten während der Journey abgefangen oder geleakt werden.

Die iFrame-Isolation schützt auch die Integrität der Unico-Skripte zur Laufzeit. Da der Code in einem von der Seite getrennten Kontext läuft, kann er von externen Skripten weder aufgerufen noch verändert werden, was sicherstellt, dass die Journey genau so ausgeführt wird, wie sie erstellt wurde, ohne Störungen.

Aus Designgründen wird in diesem Integrationsmodell keine CSP eingesetzt. Die autorisierten Domains sind Teil der Sicherheitskonfiguration jedes Kunden, und ihre öffentliche Offenlegung in Headern könnte böswilligen Akteuren das Kartografieren der Infrastruktur erleichtern. Da die Identifizierung des Kunden erst zum Zeitpunkt des init erfolgt, ist es nicht möglich, diese Domains vor diesem Punkt dynamisch in die Header einzufügen, was eine CSP ohne Verzicht auf diese Vertraulichkeit unmöglich macht. Alle Sicherheitsgarantien werden durch das oben beschriebene Handshake-Protokoll bereitgestellt.

SDK-spezifische Fehlerbehebung

Dieser Abschnitt behandelt die häufigsten Probleme, die bei der Integration auftreten, und die empfohlenen Wege, sie zu untersuchen.

Unerwartetes Verhalten oder unterbrochener Flow

Prüfen Sie, ob ein Skript der Anwendung den iFrame direkt im DOM manipuliert. Das SDK erstellt und verwaltet den iFrame im body der Seite, und jede externe Änderung (an Geltungsbereich, Positionierung oder Attributen) kann den Lebenszyklus der Journey stören und unvorhersehbares Verhalten verursachen.

Visuelles Erlebnis weicht vom Erwarteten ab

Prü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 Klassenselektoren erheblich reduziert. Dennoch können CSS-Regeln mit breitem Geltungsbereich (wie Tag-Selektoren) Elemente innerhalb des iFrames erreichen und das dem Nutzer gelieferte visuelle Erlebnis verändern.

Bibliotheksdateien des SDK direkt verändert

Prüfen Sie, ob eine Bibliotheksdatei außerhalb des Paketmanagers verändert wurde. Die Bibliothek muss ausschließlich über npm oder yarn verwaltet werden, ohne direkte Änderungen an den installierten Dateien. Manuelle Änderungen können anomales, schwer reproduzierbares Verhalten verursachen und verhindern die Unterstützung durch den Unico-Support.

Direktzugriff

Der Nutzer wird auf einen von Unico gehosteten Link weitergeleitet, wo die Journey stattfindet. Nach Abschluss wird er zu der bei der Prozesserstellung definierten URL zurückgeleitet (Parameter callbackUri).

Dies ist der am einfachsten umzusetzende Ansatz: Er erfordert keine Bibliotheksinstallation und eignet sich gut, wenn die Journey nicht innerhalb der eigenen Seite der Anwendung stattfinden muss. Andererseits führt das Verlassen der Umgebung des Kunden tendenziell zu mehr Reibung und damit zu einer höheren Abbruchrate.

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

• Standard-Redirect. Der Nutzer wird direkt zur Journey-URL weitergeleitet. Nach Abschluss leitet Unico ihn zurück zum bei der Prozesserstellung definierten callbackUri.
• Neuer Tab mit window.open(). Die Journey wird in einem neuen Browser-Tab geöffnet, sodass der Nutzer in einem separaten Kontext bleibt. In diesem Fall wird empfohlen, auf einen URL-Wechsel zum callbackUri zu achten und den Tab zu schließen, sobald der Prozess abgeschlossen ist. Weitere Details zur API finden Sie in der MDN-Dokumentation.

In mobilen Anwendungen ist es üblich, eine WebView zu verwenden, um die Journey direkt zu öffnen, ohne zusätzliche Weiterleitung. In diesem Fall akzeptiert der callbackUri auch einen Deeplink, sodass der Abschluss der Journey das Öffnen eines bestimmten Bildschirms in der nativen Anwendung auslösen kann. Konfigurieren Sie den Deeplink einfach als Rückkehrziel, und das Betriebssystem übernimmt das Routing des Nutzers an die richtige Stelle. Dieser WebView-Ansatz eignet sich für Apps, die bereits eine WebView einbetten; eine vollständig native App sollte das plattformspezifische SDK bevorzugen.

Lassen Sie die DevTools während der Erfassungstests nicht geöffnet

Unico verwendet mehrere Mechanismen, um seine Journeys abzusichern. Einer davon erkennt geöffnete DevTools als mögliches Betrugssignal und blockiert die Übermittlung. Schließen Sie die DevTools, bevor Sie End-to-End-Erfassungstests ausführen.

Nicht unterstützte Integrationen

Die in dieser Dokumentation beschriebenen Modelle (Direktzugriff und Journeys SDK) sind die einzigen von Unico offiziell unterstützten Integrationsansätze. Integrationen, die von diesen Standards abweichen, können unerwartetes Verhalten, Fehler im Sicherheitsfluss und Unterbrechungen der Journey verursachen und werden vom Unico-Support nicht abgedeckt.

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

• Das SDK in eine WebView einbetten in mobilen Anwendungen. In diesen Fällen ist der richtige Weg, das Modell Direktzugriff zu verwenden und den Journey-Link direkt in der WebView zu öffnen, ohne das Journeys SDK einzubeziehen.
• Den iFrame direkt über ein <iframe>-HTML-Tag laden, ohne das Journeys SDK zu verwenden. Der iFrame ist ein internes Implementierungsdetail des SDK und darf nicht manuell instanziiert werden. Der richtige Weg ist die Verwendung des Journeys SDK, das den Lebenszyklus des iFrames sicher und innerhalb der erwarteten Standards verwaltet.

Falls Zweifel bestehen, ob ein Ansatz dem unterstützten Standard entspricht, konsultieren Sie die Dokumentation oder wenden Sie sich an den Support, bevor Sie mit der Implementierung fortfahren.