--- title: Web-App-Integration description: So integrieren Sie den Web-&-SDK-Vertrag auf der Client-Seite — Redirect-Flows und iFrame-SDK-Einrichtung. canonical: https://developer.unico.io/de/dual-api/developers/sdks-and-tools/web/web-integration/ locale: de generated_by: markdown-export --- 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. :::tip[Die passende Integrationsmethode wählen] - **Web SDK** (Paket `unico-webframe`): Verwenden Sie es, wenn Ihr Back-End den Identitätsprüfungs-Flow bereits steuert und nur die clientseitige Erfassungskomponente benötigt. Gibt `base64` + verschlüsseltes JWT direkt an Ihren Callback zurück; Sie verwalten die API-Aufrufe. - **Web App Integration** (Paket `idpay-b2b-sdk`): Verwenden Sie es, wenn Unico die gesamte Journey orchestrieren soll (mehrstufige Flows, Dokumentenerfassung + Lebenderkennung). Das Paket `idpay-b2b-sdk` betreibt das eingebettete **Journeys SDK**-Modell (iFrame); das **Direktzugriff**-Modell (Redirect) benötigt keine Bibliothek. ::: ## Zwei Integrationsmodelle Jeder Kunde hat unterschiedliche Anforderungen. Unico bietet **zwei Modelle**, um den Nutzer zur Journey zu leiten. | Modell | Am besten geeignet für | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------- | | **Direktzugriff** | Mobile Anwendungen, die bereits WebView verwenden, oder Web-Flows, bei denen die Journey außerhalb der Hauptseite stattfinden kann | | **Journeys SDK** | Web-Anwendungen, die ein integriertes, nahtloses Erlebnis benötigen und den Nutzer in derselben Umgebung halten | ### 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](https://developer.mozilla.org/en-US/docs/Web/API/Window/open). ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant Frontend as Customer frontend application participant Hosted as Unico hosted frontend application Frontend->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>Frontend: return Unico process info Frontend->>Hosted: redirect user to process url Note over Hosted: User journey Hosted->>Frontend: redirect user to callback url critical Get process result Frontend->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` 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. ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant App as Customer mobile application participant Hosted as Unico hosted frontend application App->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>App: return Unico process info App->>Hosted: open the process url in a webview Note over Hosted: User journey Hosted->>App: redirect user to the deeplink (callback url) critical Get process result App->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` ### 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 `idpay-b2b-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. ```bash npm install idpay-b2b-sdk ``` 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. :::tip[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 | ```javascript import { ByUnicoSDK } from 'idpay-b2b-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. :::warning 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. ```javascript 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: ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant Frontend as Customer frontend application participant SDK as ByUnicoSDK Frontend->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>Frontend: return Unico process info Note over Frontend: Initialize the Unico journey as soon as it is determined that the KYC flow is required critical Unico journey initialization Frontend->>SDK: byUnicoSDK.init SDK-->>Frontend: validates customer domain and initialize end critical Unico journey exhibition Frontend->>SDK: byUnicoSDK.open SDK-->>Frontend: show byUnico experience end Note over SDK: User journey critical Unico journey completion SDK-->>Frontend: call onFinish end critical Get process result Frontend->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` #### Beispiel-Apps | Sprache / Framework | Beschreibung | Repository | | --------------------- | ------------ | ---------- | | Angular | PoC in Angular, das das Journeys SDK implementiert | [GitHub — unico-cbu-poc-angular](https://github.com/unico-labs/unico-cbu-poc-angular) | | JS Vanilla | PoC in JS Vanilla, das das Journeys SDK implementiert | [GitHub — unico-cbu-poc-js](https://github.com/unico-labs/unico-cbu-poc-js) | | React | PoC in React, das das Journeys SDK implementiert | [GitHub — unico-cbu-poc-react](https://github.com/unico-labs/unico-cbu-poc-react) | | Vue JS | PoC in Vue JS, das das Journeys SDK implementiert | [GitHub — unico-cbu-poc-vuejs](https://github.com/unico-labs/unico-cbu-poc-vuejs) | #### Sicherheit :::note[Geltungsbereich dieses Abschnitts] Diese Sicherheitsbegründung gilt speziell für die **Web App Integration** (`idpay-b2b-sdk`). Das **Web SDK** (`unico-webframe`) verwendet ein anderes Modell: Es läuft vollständig im Seitenkontext und [erfordert eine CSP](/dual-api/developers/sdks-and-tools/web/web-sdk/installation). Dies sind zwei unterschiedliche Produkte mit verschiedenen Sicherheitsarchitekturen. ::: 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. #### Lassen Sie die DevTools während der Erfassungstests nicht geöffnet Die Unico-Anwendung verwendet das Capture SDK (unico-webframe) für die Gesichtserfassung, das geöffnete DevTools als mögliches Betrugssignal erkennt und die Übermittlung blockiert. Schließen Sie die DevTools, bevor Sie End-to-End-Erfassungstests ausführen. :::warning[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 `