--- 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/human-token/integrations/web/web-integration/ locale: de generated_by: markdown-export --- 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](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) für Details zur API. ```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 `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. ```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 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. ```bash 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. :::tip[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"); ``` :::info 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 | ```javascript 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. :::warning 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. ```javascript 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: ```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 ``` #### Beispielanwendungen | Sprache / Framework | Beschreibung | Repository | | --------------------- | ------------ | ---------- | | Angular | PoC in Angular, die das Journeys SDK implementiert | [GitHub — unico-cbu-poc-angular](https://github.com/unico-labs/unico-cbu-poc-angular) | | JS Vanilla | PoC in JS Vanilla, die das Journeys SDK implementiert | [GitHub — unico-cbu-poc-js](https://github.com/unico-labs/unico-cbu-poc-js) | | React | PoC in React, die das Journeys SDK implementiert | [GitHub — unico-cbu-poc-react](https://github.com/unico-labs/unico-cbu-poc-react) | | Vue JS | PoC in Vue JS, die das Journeys SDK implementiert | [GitHub — unico-cbu-poc-vuejs](https://github.com/unico-labs/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. :::warning[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 `