Web-App-Integration

Diese Seite beschreibt die beiden clientseitigen Integrationsansätze für den Web-&-SDK-Vertrag: die Weiterleitung des Benutzers zu einer von Unico gehosteten Journey und die Einbettung der Journey über das iFrame-SDK.

Benutzer weiterleiten

Nach dem Erstellen eines Prozesses enthält die Antwort eine URL, die auf die von Unico gehostete Journey verweist. Verwenden Sie diese URL, um den Benutzer zur Erfassungserfahrung weiterzuleiten. Es gibt zwei Möglichkeiten, diesen Übergang zu verwalten:

1. Standard-Redirect

Leiten Sie den Benutzer direkt zur Journey-URL weiter. Wenn der Benutzer den Prozess abschließt, leitet Unico ihn zurück zu der URL weiter, die Sie bei der Prozesserstellung angegeben haben.

2. Neuer Tab mit window.open()

Öffnen Sie die Journey in einem neuen Browser-Tab, damit der Benutzer in einem separaten Kontext bleibt. Überwachen Sie eine URL-Änderung zu Ihrer Rückgabe-URL und schließen Sie den Tab, wenn der Prozess abgeschlossen ist.

Weitere Details zur window.open()-API finden Sie in der MDN-Dokumentation.

iFrame

Warnung

Integrationen, die nicht den Standards dieser Dokumentation entsprechen, können zu unerwarteten Unterbrechungen führen und werden nicht vom Unico-Support abgedeckt.

Beispiele für nicht unterstützte Ansätze: das SDK in eine WebView einbetten oder das iFrame direkt über ein HTML-Tag laden.

Erste Schritte

Schritt 1 — Installation

Das by Unico SDK verwendet dasselbe Paket wie IDPay:

npm install idpay-b2b-sdk

Tipp

Installieren Sie ohne Angabe einer bestimmten Version, damit Ihr Paketmanager automatisch immer die neuesten Minor- und Patch-Releases herunterlädt.

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 Assets vorab, was für den Endbenutzer eine flüssigere Erfahrung schafft. Rufen Sie dies so früh wie möglich in Ihrem Flow auf.

Parameter	Erforderlich	Beschreibung
type	Ja	Auf 'IFRAME' für by Unico Flows setzen
token	Ja	Prozess-Token, der von der Create Process API zurückgegeben wird
env	Nein	Nur für Testumgebungen auf 'uat' setzen

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

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

Schritt 3 — open(options) aufrufen

Zeigt das vorgeladene iFrame an und startet den Nachrichtenfluss zwischen Ihrer Seite und der Unico Journey.

Parameter	Erforderlich	Beschreibung
transactionId	Ja	Prozess-ID, die von der Create Process API zurückgegeben wird
token	Ja	Prozess-Token, der von der Create Process API zurückgegeben wird
onFinish	Ja	Callback, der ausgeführt wird, wenn die Journey endet oder geschlossen wird

Der onFinish-Callback erhält ein Prozess-Objekt mit der Transaktions-ID, einer Weiterleitungs-URL und dem Abschlusstyp.

ByUnicoSDK.open({
  transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  onFinish: (process) => {
    console.log('Process finished', process);
    // process.transaction.redirectUrl — use this to navigate the user
  },
});

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

Das nachfolgende Sequenzdiagramm zeigt, wie das SDK und das API-Ergebnis zur Konfiguration des iFrames verwendet werden:

Sicherheit

Die iFrame-Lösung mit Auth-Token statt CSP bevorzugen

Nach sorgfältiger Analyse verwendet der gewählte Ansatz iFrames mit Authentifizierungstoken anstelle der Implementierung einer Content Security Policy (CSP). Diese Entscheidung wurde durch die Sicherheitsanforderungen und die notwendige Flexibilität zur Erfüllung von Kundenanforderungen motiviert.

Kontext und Herausforderungen mit CSP

Content Security Policy ist ein leistungsstarkes Werkzeug zum Schutz von Webanwendungen gegen XSS- und Code-Injection-Angriffe. Die Konfiguration einer CSP-Richtlinie erfordert jedoch die Definition einer strengen Liste vertrauenswürdiger Domains. Dieser Ansatz ist wirksam, wenn Domains fest und vorhersehbar sind — aber für Kunden, die dynamische und variable Domains verwenden, stellt diese starre Konfiguration erhebliche Herausforderungen dar.

Schwachstelle bei dynamischen Domains

Dynamische Domains stellen bei der Verwendung von CSP ein erhebliches Sicherheitsrisiko dar. Wenn ein Kunde Domains hat, die sich häufig ändern oder dynamisch erstellt werden, muss die CSP-Richtlinie ständig aktualisiert werden, um neue Domains einzubeziehen. Dies erhöht nicht nur den Wartungsaufwand, sondern macht auch jede in der Richtlinie aufgeführte Domain zu einer potenziellen Angriffsfläche, wenn sie nicht angemessen verwaltet wird.

Lösung mit iFrame und Auth-Token

Um diese Risiken zu mindern und die von Kunden geforderte Flexibilität zu erfüllen, kombiniert die gewählte Lösung iFrames mit Authentifizierungstoken und bietet so eine zusätzliche Sicherheitsebene, ohne eine statische Domain-Liste zu benötigen.

Funktionsweise:

• Sichere Authentifizierung — jedes iFrame wird mit einem eindeutigen Authentifizierungstoken pro Transaktion geladen, wodurch sichergestellt wird, dass nur autorisierte Benutzer auf den Inhalt zugreifen können. Das Token wird in Echtzeit überprüft.
• Inhaltsisolierung — das iFrame wird in einem separaten Browsing-Kontext ausgeführt, wodurch das Risiko von Interferenzen zwischen verschiedenen Ursprüngen reduziert und potenzielle Angriffe gemindert werden.
• Flexibilität für dynamische Domains — da keine statische CSP-Richtlinie verwendet wird, passt sich die Lösung dynamischen Client-Domains an, ohne dass ständige Richtlinienaktualisierungen erforderlich sind.