Integration by means of iFrame

signoSign/Universal is often embedded in an existing web application as iFrame. An example of this can be found when the application is running in our REST API Showcase, if devTools are activated. For this type of integration, signoSign/Universal provides public Javascript methods and events, which are also documented in this section.

General information

If the surrounding web application and signoSign/Universal are operated under the same domain, an iFrame integration should be straightforward. If problems do occur in this scenario, however, the ssmPublicUrl setting may not be set correctly; also bear in mind that most browsers do not permit the mixing of HTTP content on HTTPS pages (and vice versa).

If there are problems with integration, in many cases the browser’s Javascript console can provide information about the cause.

Cross-origin resource sharing

If the surrounding web application and signoSign/Universal are not operated on the same domain, the embedding of signoSign/Universal as iFrame must be permitted at HTTP protocol level. This means that the headers Access-Control-Allow-Origin and Access-Control-Allow-Methods must be added to every HTTP response.

These HTTP headers can be added either by configuring the server or by activating the integrated CORS filter. The configuration of the CORS filter is already included in the web.xml of signoSign/Universal, but it is commented out. The web.xml is located in the WEB-INF folder of the WAR or EAR.

Cookies

The authentication to signoSign/Universal is specified in cookies. For operation in the iFrame, however, the signoSign/Universal cookie is requested from the surrounding web application. If the surrounding web application is running under a domain other than signoSign/Universal, this cookie must explicitly allow the access of external domains.

This behaviour is defined with the SameSite attribute of a cookie and must have the value Lax for iFrame operation. This can generally be configured on the server that is used.

Specially for Apache Tomcat, a context.xml is supplied in the META-INF folder of the signoSign/Universal WAR. The SameSite attribute is preset to Strict.

Public JavaScript functions

If signoSign/Universal is called in an iFrame from a surrounding application, there are a number of publicly documented functions in JavaScript code that can be executed via the iFrame element.

For example, the following snippet of code executes the save function:

JS

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

The Viewer provides the following functions:

Function	Description
`logout`	Logs the current session out of the server.
`fitPageToStandardDocumentSize`	Displays the pages of the document no larger than the rendered size.
`fitPageToScreenHeight`	Aligns the document with the page height. This means that the upper and lower edges of the document can be seen.
`fitPageToScreenWidth`	Aligns the document with the page width. This means that the left-hand and right-hand edges of the document can be seen.
`showThumbnails`	Displays the thumbnail menu of the application, which can be used to scroll to a certain page in the document.
`startSharingCaseCreation`	Launches the dialog box to share a document.
`showSummarySignaturesDialog`	Displays a dialog box with a list of all empty signature fields contained in the document.
`startSigningProcess`	Starts the signing process.
`addSignatureField`	Starts the process to add another signature field.
`insertNote`	Starts the process to insert a note into the document.
`saveDocument`	Starts the save process.
`showNextPage`	Scrolls to the next page of the document.
`showPrevPage`	Scrolls to the previous page of the document.
`showSaveBeforeLeaveDialog`	Opens the dialog box that is displayed if a document contains unsaved changes. If this function is explicitly called, the dialog box is displayed regardless of whether there are changes in the document.
`showPage`	Scrolls to a certain page. The pageNumber parameter determines the number of the page to be displayed. The values must be `integers > 0`.

JavaScript events

If signoSign/Universal is embedded in another application as an iFrame, the surrounding application can be informed of certain events.

Depending on the event, the behaviour of signoSign/Universal can be influenced by calling the preventDefault method of the object transferred to the event within the defined event handler.

The following snippet of code shows how a surrounding application defines an event handler for SSUMessageEvent.

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

Executed when signoSign/Universal displays information or an error message.

Default behavior:
signoSign/Universal displays the message that appears as a separate dialog box.

PreventDefault():
The message that appears is not displayed in a dialog box in signoSign/Universal. The surrounding application can handle the message itself.

Parameter	Description	Attributes	Attribute description	Values
severity	Describes the type of message.	-	-	`"ERROR", "INFO"`
message	The localised message text.	-	-	`String`
MessageKey	The key value under which the localised message can be found in the locales.	-	-	`String`

SSUSignaturePerformedEvent

Executed when a signature is captured and sent to the server.

Parameter	Description	Attributes	Attribute descriptions	Values
signatureFieldsStatus	An array of objects that supply information to all the signature fields found in the document	isSigned	Displays whether the signature field has been signed	`true / false`
		isMandatory	Displays whether the signature field is mandatory	`true / false`
		htmlId	The HTML ID of the signature field	`String`
		formFieldName	The form field name of the signature field in the PDF	`String`
		page	The number of the page on which the signature field is located	`Integer > 0`
signedSignatureFieldIndex	The index of the signature field that has been signed	-	-	`Integer > 0`

SSUDocumentSavedEvent

Executed as soon as the save process has been carried out

Parameter	Description	Attributes	Attribute descriptions	Values
signatureFieldsStatus	An array of objects that supply information to all the signature fields found in the document	isSigned	Displays whether the signature field has been signed	`true / false`
		isMandatory	Displays whether the signature field is mandatory	`true / false`
		htmlId	The HTML ID of the signature field	`String`
		formFieldName	The form field name of the signature field in the PDF	`String`
		page	The page number on which the signature field is located	`Integer > 0`
successful	A Boolean value as to whether or not the save process was successful	-	-	`true / false`

SSUUpdateFormFieldsEvent

Executed when form fields changed by the user are synchronised with the backend.

Default behavior:
All user entries are transferred to the server and written in the server-side representation of the document.

PreventDefault():
Prevents synchronization between the frontend and backend. The entries are not inserted into the document.

Parameter	Description	Attributes	Attribute descriptions	Values
formFieldStatus	An array of objects that contain information about each individual form field.	oldValue	The value of the form field before the change	`String`
		value	New value of the form field	`String`
		htmlId	The HTML ID of the form field	`String`
		formFieldName	Name of the form field in the PDF	`String`
		isDirty	Displays whether the value of the field has changed	`true / false`

SSUPadOpenedEvent

Executed as soon as a connection to a signature device has been opened

Parameter	Description	Attributes	Attribute description	Values
padType	Specification of the pad type as a numeric value	-	-	`Integer > 0`
padSerial	The serial number of the opened pad	-	-	`String`
padVersion	Firmware version of the opened pad	-	-	`String`

SSUPadClosedEvent

Executed as soon as a connection to a signature device has been closed.

Parameter	Description	Attributes	Attribute description	Values
padType	Specification of the pad type as a numeric value	-	-	`Integer > 0`
padSerial	The serial number of the opened pad	-	-	`String`
padVersion	Firmware version of the opened pad	-	-	`String`

SSUPadStateChangedEvent

Executed as soon as the status of the opened pad changes. A signature device can have one of the following statuses:

Status	Description
READY	The signature device is ready to capture a signature.
PREPARING	The signature device has started to prepare the signing process.
CANCELLING	A signing process has been cancelled.
RETRYING	A signing process has been restarted.
SKIPPING	A signing process has been skipped.
CONFIRMING	A signing process has been confirmed.
STOPPED	A signing process has been stopped.
PAD_CERT_VALIDATION_FAILED	Executed if the certificate saved in the signature device cannot be verified against the certificate chain defined on the server.
NO_PAD_FOUND	Executed if no signature device was found.

Parameter	Description	Attributes	Attribute description	Values
padStatus	The status assumed by the signature device.	-	-	`"READY", "PREPARING", "CANCELLING", "RETRYING", "CONFIRMING", "STOPPED", "PAD_CERT_VALIDATION_FAILED", "SHOW_DOCUMENT_ON_PAD_RUNNING", "NO_PAD_FOUND"`

SSUSignatureStartEvent

Triggered once a signature process has been started.

Default behavior:
The signing dialog box is opened.

PreventDefault():
Opening of the signing dialog box is prevented.

Parameter	Description	Attributes	Attribute description	Values
isMandatory	Specifies whether the started signature is a mandatory field.	-	-	`true / false`
htmlId	The ID of the DOM element within the Viewer	-	-	`String`
formFieldName	The technical form field name of the signature field in the PDF.	-	-	`String`
page	The page in the PDF on which the signature field is located.	-	-	`Integer > 0`

SSUFormFieldFocusEvent

Triggered when a form field is focused on.

Default behavior:
The addressed form field is focused on.

PreventDefault():
Focusing on the form field is prevented.

Parameter	Description	Attributes	Attribute description	Values
isMandatory	Specifies whether the started signature is a mandatory field.	-	-	`true / false`
htmlId	The ID of the DOM element within the Viewer.	-	-	`String`
formFieldName	The technical form field name of the signature field in the PDF.	-	-	`String`
page	The page in the PDF on which the signature field is located.	-	-	`Integer > 0`
type	Specifies the type of form field.	-	-	`"text", "area", "combobox", "listbox", "checkbox"`

SSUDocumentLoadedEvent

Triggered once the document is ready/has been loaded in the Viewer. No parameters are transferred to this event.

SSUPageNumberChangeEvent

Triggered if another page in the document is changed to.

Parameter	Description	Attributes	Attribute description	Values
newPageNumber	The page number of the new page to be displayed.	-	-	`Integer > 0`