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

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:

JS

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

Folgende Funktionen stellt der Viewer bereit:

Funktion	Beschreibung
`logout`	Meldet die aktuelle Session am Server ab.
`fitPageToStandardDocumentSize`	Zeigt die Seiten des Dokuments maximal in der gerenderten Größe an.
`fitPageToScreenHeight`	Richtet das Dokument an der Seitenhöhe aus. Das bedeutet, dass die obere und untere Kante des Dokumentes zu sehen sind.
`fitPageToScreenWidth`	Richtet das Dokument an der Seitenbreite aus. Das bedeutet, dass die linke und rechte Kante des Dokumentes zu sehen sind.
`showThumbnails`	Zeigt das Thumbnail-Menü der Anwendung an, über das zu einer bestimmten Seite geblättert werden kann.
`startSharingCaseCreation`	Startet den Dialog zum Teilen eines Dokuments.
`showSummarySignaturesDialog`	Zeigt einen Dialog mit einer Liste aller im Dokument enthaltenen leeren Signaturfelder an.
`startSigningProcess`	Startet den Signaturprozess.
`addSignatureField`	Startet den Prozess zum Hinzufügen eines weiteren Signaturfeldes.
`insertNote`	Startet den Prozess zum Einbringen einer Notiz ins Dokument.
`saveDocument`	Startet den Speichernprozess.
`showNextPage`	Blättert zur nächsten Seite des Dokuments.
`showPrevPage`	Blättert zur vorherigen Seite des Dokuments.
`showSaveBeforeLeaveDialog`	Öffnet den Dialog, der angezeigt wird, wenn ein Dokument ungespeicherte Änderungen enthält. Sofern diese Funktion explizit aufgerufen wird, wird der Dialog angezeigt unabhängig davon, ob sich Änderungen im Dokument befinden.
`showPage`	Blättert zu einer bestimmten Seite. Der Parameter pageNumber bestimmt die Nummer der Seite, die angezeigt werden soll. Die Werte müssen `Integer > 0` sein.

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.

JS

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.

Parameter	Beschreibung	Attribute	Attributbeschreibung	Werte
severity	Beschreibt die Art der Meldung.	-	-	`"ERROR", "INFO"`
message	Der lokalisierte Meldungstext.	-	-	`String`
MessageKey	Der Schlüssel-Wert, unter dem die lokalisierte Nachricht in den Locales zu finden ist.	-	-	`String`

SSUSignaturePerformedEvent

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

Parameter	Beschreibung	Attribute	Attributsbeschreibungen	Werte
signatureFieldsStatus	Ein Array aus Objekten, die Informationen zu allen im Dokument befindlichen Signaturfeldern liefern.	isSigned	Zeigt an, ob das Signaturfeld unterschrieben ist.	`true / false`
		isMandatory	Zeigt an, ob es sich um ein obligatorischen Signaturfeld handelt.	`true / false`
		htmlId	Die HTML-ID des Signaturfeldes.	`String`
		formFieldName	Der Formularfeldname des Signaturfeldes im PDF.	`String`
		page	Die Nummer der Seite, auf der sich das Signaturfeld befindet.	`Integer > 0`
signedSignatureFieldIndex	Der Index des Signaturfeldes, welches unterschrieben wurde.	-	-	`Integer > 0`

SSUDocumentSavedEvent

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

Parameter	Beschreibung	Attribute	Attributsbeschreibungen	Werte
signatureFieldsStatus	Ein Array aus Objekten, die Informationen zu allen im Dokument befindlichen Signaturfeldern liefern.	isSigned	Zeigt an, ob das Signaturfeld unterschrieben ist.	`true / false`
		isMandatory	Zeigt an, ob es sich um ein obligatorischen Signaturfeld handelt.	`true / false`
		htmlId	Die HTML-ID des Signaturfeldes.	`String`
		formFieldName	Der Formularfeldname des Signaturfeldes im PDF.	`String`
		page	Die Seitennummer auf der sich das Signaturfeld befindet.	`Integer > 0`
successful	Ein boolescher Wert, ob der Speichernprozess erfolgreich war oder nicht.	-	-	`true / false`

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.

Parameter	Beschreibung	Attribute	Attributsbeschreibungen	Werte
formFieldStatus	Ein Array aus Objekten, welche Informationen über jedes einzelne Formularfeld enthält.	oldValue	Der Wert des Formularfeldes vor der Änderung.	`String`
		value	Neuer Wert des Formularfelds.	`String`
		htmlId	Die HTML-ID des Formularfelds.	`String`
		formFieldName	Name des Formularfeldes im PDF.	`String`
		isDirty	Zeigt an, ob der Wert des Feldes sich geändert hat.	`true / false`

SSUPadOpenedEvent

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

Parameter	Beschreibung	Attribute	Attributbeschreibung	Werte
padType	Die Angabe des Pad-Typs als numerischer Wert.	-	-	`Integer > 0`
padSerial	Die Seriennummer des geöffneten Pads.	-	-	`String`
padVersion	Die Firmware-Version des geöffneten Pads.	-	-	`String`

SSUPadClosedEvent

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

Parameter	Beschreibung	Attribute	Attributbeschreibung	Werte
padType	Die Angabe des Pad-Typs als numerischer Wert.	-	-	`Integer > 0`
padSerial	Die Seriennummer des geöffneten Pads.	-	-	`String`
padVersion	Firmware-Version des geöffneten Pads.	-	-	`String`

SSUPadStateChangedEvent

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

Status	Beschreibung
READY	Das Signaturgerät ist bereit, eine Unterschrift zu erfassen.
PREPARING	Das Signaturgerät hat begonnen, den Signaturvorgang vorzubereiten.
CANCELLING	Ein Signaturvorgang wurde abgebrochen.
RETRYING	Ein Signaturvorgang wurde neugestartet.
SKIPPING	Ein Signaturvorgang wurde übersprungen.
CONFIRMING	Ein Signaturvorgang wurde bestätigt.
STOPPED	Ein Signaturvorgang wurde gestoppt.
PAD_CERT_VALIDATION_FAILED	Wird ausgelöst, wenn das im Signaturgerät gespeicherte Zertifikat sich nicht gegen die am Server definierte Zertifikatskette prüfen lässt.
NO_PAD_FOUND	Wird ausgelöst, wenn kein Signaturgerät gefunden werden konnte.

Parameter	Beschreibung	Attribute	Attributbeschreibung	Werte
padStatus	Der Status, den das Signaturgerät angenommen hat.	-	-	`"READY", "PREPARING", "CANCELLING", "RETRYING", "CONFIRMING", "STOPPED", "PAD_CERT_VALIDATION_FAILED", "SHOW_DOCUMENT_ON_PAD_RUNNING", "NO_PAD_FOUND"`

SSUSignatureStartEvent

Wird ausgelöst, sobald ein Signaturprozess gestartet wird.

Standardverhalten:
Der Signierdialog wird geöffnet.

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

Parameter	Beschreibung	Attribute	Attributbeschreibung	Werte
isMandatory	Die Angabe, ob es sich bei der gestarteten Signatur um ein Pflichtfeld handelt.	-	-	`true / false`
htmlId	Die ID des DOM-Elements innerhalb des Viewers	-	-	`String`
formFieldName	Der technische Formularfeldname des Signaturfeldes im PDF.	-	-	`String`
page	Die Seite im PDF, auf dem sich das Signaturfeld befindet.	-	-	`Integer > 0`

SSUFormFieldFocusEvent

Wird ausgelöst, wenn ein Formularfeld fokussiert wird.

Standardverhalten:
Das angesprochene Formularfeld wird fokussiert.

PreventDefault():
Das fokussieren des Formularfeldes wird unterbunden.

Parameter	Beschreibung	Attribute	Attributbeschreibung	Werte
isMandatory	Die Angabe, ob es sich bei der gestarteten Signatur um ein Pflichtfeld handelt.	-	-	`true / false`
htmlId	Die ID des DOM-Elements innerhalb des Viewers.	-	-	`String`
formFieldName	Der technische Formularfeldname des Signaturfeldes im PDF.	-	-	`String`
page	Die Seite im PDF, auf dem sich das Signaturfeld befindet.	-	-	`Integer > 0`
type	Gibt den Typ des Formularfeldes an.	-	-	`"text", "area", "combobox", "listbox", "checkbox"`

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.

Parameter	Beschreibung	Attribute	Attributbeschreibung	Werte
newPageNumber	Die Seitennummer der neu anzuzeigenden Seite.	-	-	`Integer > 0`