Integration mittels iFrame

Häufig wird signoSign/Universal in eine bereits bestehende Webanwendung als iFrame eingebettet. Ein Beispiel dazu ist bei laufender Anwendung in unserem REST-API Showcase zu finden, sofern die devTools aktiviert sind. Für diese Art der Integration stellt signoSign/Universal öffentliche Javascript- Methoden und - Events bereit, die ebenfalls in diesem Kapitel dokumentiert sind.

• Allgemeine Hinweise

• Cross-Origin-Resource Sharing

• Cookies

• Öffentliche JavaScript-Funktionen

• JavaScript-Events

  • SSUMessageEvent

  • SSUSignaturePerformedEvent

  • SSUDocumentSavedEvent

  • SSUUpdateFormFieldsEvent

  • SSUPadOpenedEvent

  • SSUPadClosedEvent

  • SSUPadStateChangedEvent

  • SSUSignatureStartEvent

  • SSUFormFieldFocusEvent

  • SSUDocumentLoadedEvent

  • SSUPageNumberChangeEvent

Allgemeine Hinweise

Sofern die umschließende Webanwendung und signoSign/Universal unter der gleichen Domain betrieben werden, sollte eine iFrame-Integration problemlos möglich sein. Sollte es jedoch auch in diesem Szenario zu Problemen kommen, ist eventuell die ssmPublicUrl-Einstellung nicht richtig gesetzt und beachten Sie, dass die meisten Browser kein Mischen von HTTP-Inhalten auf HTTPS-Seiten (und umgekehrt) zulassen.

Bei Problemen mit der Integration kann in den vielen Fällen die Javascript-Konsole des Browsers Aufschluss über die Ursache geben.

Cross-Origin-Resource Sharing

Sofern die umschließende Webanwendung und signoSign/Universal nicht auf der gleichen Domain betrieben werden, muss das Einbetten von signoSign/Universal als iFrame auf HTTP-Protokollebene erlaubt sein. Das bedeutet, dass jeder HTTP-Response die Header Access-Control-Allow-Origin und Access-Control-Allow-Methods hinzugefügt werden müssen.

Das Einfügen dieser HTTP-Header kann entweder durch Konfiguration des Servers oder durch Aktivierung des integrierten CORS-Filters. Die Konfiguration des CORS-Filters ist bereits in der web.xml von signoSign/Universal enthalten, ist aber auskommentiert. Die web.xml befindet sich im WEB-INF-Ordner des WARs bzw. EARs.

Cookies

Die Authentifizierung an signoSign/Universal wird in Cookies festgehalten. Bei Betrieb im iFrame wird das signoSign/Universal-Cookie aber von der umschließende Webanwendung angefragt. Läuft die umschließende Webanwendung unter einer anderen Domain als signoSign/Universal, muss dieses Cookie den Zugriff von fremden Domains ausdrücklich erlauben.

Dieses Verhalten wird mit dem SameSite-Attribut eines Cookies definiert und muss für den iFrame-Betrieb den Wert Lax haben. Das kann in der Regel am verwendeten Server konfiguriert werden.

Speziell für den Apache Tomcat, wird eine context.xml im META-INF-Ordner des signoSign/Universal-WAR ausgeliefert. Darin wird das SameSite-Attribut im Auslieferungszustand auf Strict gesetzt.

Öffentliche JavaScript-Funktionen

Wird signoSign/Universal in einem iFrame aus einer umschließenden Anwendung heraus aufgerufen, existiert eine Menge an öffentlich dokumentierten Funktionen im JavaScript-Code, die über das iFrame-Element ausgeführt werden können.

Folgender Code-Ausschnitt führt beispielhaft die Speichern-Funktion aus:

iframe = document.getElementById("iframe");
iframe.contentWindow.viewerFunctions.saveDocument();

Folgende Funktionen stellt der Viewer bereit:

JavaScript-Events

Wird signoSign/Universal als iFrame in eine andere Anwendung eingebettet, kann die umschließende Anwendung über bestimmte Ereignisse informiert werden.

Abhängig vom Ereignis kann das Verhalten von signoSign/Universal beeinflusst werden, indem innerhalb des definierten Eventhandlers die Methode preventDefault des an das Event übergebenen Objektes aufgerufen wird.

Der folgende Code-Ausschnitt zeigt wie eine umschließende Anwendung einen Eventhandler für das SSUMessageEvent definiert.

iframe = document.getElementById("iframe");
iframe.contentWindow.addEventListener("SSUMessageEvent", function(e) {
    console.info("SSUMessageEvent");
    console.info(e.detail.severity);
    console.info(e.detail.message);
});

SSUMessageEvent

Wird ausgelöst, wenn signoSign/Universal eine Information oder einen Fehler anzeigt.

Standardverhalten:
signoSign/Universal zeigt die auftretende Meldung als separaten Dialog an.

PreventDefault():
Die auftretende Meldung wird nicht in einem Dialog in signoSign/Universal angezeigt. Die umschließende Anwendung kann die Meldung selbst behandeln.

SSUSignaturePerformedEvent

Wird ausgelöst, wenn eine Unterschrift geleistet und an den Server gesendet wird.

SSUDocumentSavedEvent

Wird ausgelöst, sobald der Speichernprozess durchgeführt wurde.

SSUUpdateFormFieldsEvent

Wird ausgelöst, wenn vom Anwender geänderte Formularfelder mit dem Backend synchronisiert werden.

Standardverhalten:
Alle Eingaben des Anwenders werden an den Server übertragen und in die serverseitige Repräsentation des Dokuments geschrieben.

PreventDefault():
Verhindert die Synchronisation zwischen Front- und Backend. Die Eingaben werden nicht in das Dokument eingebracht.

SSUPadOpenedEvent

Wird ausgelöst, sobald eine Verbindung zu einem Signaturgerät geöffnet wird.

SSUPadClosedEvent

Wird ausgelöst, sobald eine Verbindung zu einem Signaturgerät geschlossen wurde.

SSUPadStateChangedEvent

Wird ausgelöst, sobald sich der Status des geöffneten Pads ändert. Ein Signaturgerät kann einen der folgenden Status annehmen:

SSUSignatureStartEvent

Wird ausgelöst, sobald ein Signaturprozess gestartet wird.

Standardverhalten:
Der Signierdialog wird geöffnet.

PreventDefault():
Das Öffnen des Signierdialogs wird unterbunden.

SSUFormFieldFocusEvent

Wird ausgelöst, wenn ein Formularfeld fokussiert wird.

Standardverhalten:
Das angesprochene Formularfeld wird fokussiert.

PreventDefault():
Das fokussieren des Formularfeldes wird unterbunden.

SSUDocumentLoadedEvent

Wird ausgelöst, sobald das Dokument fertig im Viewer geladen ist. Diesem Event werden keine Parameter übergeben.

SSUPageNumberChangeEvent

Wird ausgelöst, wenn zu einer anderen Seite im Dokument gewechselt wird.