Integration by means of iFrame | signotec Knowledge Base

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.

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. The application already sets the necessary headers in the delivery state.
In addition, the authentication cookies must be enabled for cross-site access. The cookie attribute SameSite=None; Secure is mandatory for this. This is configured via:

META-INF/context.xml in WAR
or
update-sicher at:
/conf/cataline/localhost/signoSignUniversal.xml (tomcat)

each with:

XML

<Context>
    <CookieProcessor sameSiteCookies="none" />
</Context>

For SameSite=None, the application must be operated with HTTPS, otherwise the cookies will be blocked by most browsers.

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 behavior 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.

postMessage interface

To use the Post Message interface, the parameter corsDomain must be set via PATCH/viewer/configuration.

This ensures that the functions and events of postMessage are checked for the correct domain.

Events

If the Viewer is embedded as an iFrame in another application, the surrounding application can be notified of certain events.

The following code snippet shows how an enclosing application defines an event handler for the SSUMessageEvent.

        
            window.addEventListener("message", function(e) {
                if (e.data.eventType == "SSUMessageEvent") {
                    console.log(e.data.detail.severity);
                    console.log(e.data.detail.message);
                }
            });

All possible events are described in detail below.

SSUMessageEvent

Triggered when the Viewer displays information or an error.

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

Parameter	Description	Attributes	Attribute description	Values
severity	Describes the type of message.	-	-	`‘ERROR,‘ ‘INFO‘`
message	The localized message text.	-	-	`String`
MessageKey	The key value under which the localized 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 synchronized with the backend.

Default behavior:
All user entries are transferred to the server and written in the server-side representation of 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 signotec 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

Triggered as soon as the status of the open signing device changes. A signing device can assume 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 canceled.
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	Triggered if the certificate stored 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.

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.

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`

SSUIsDirtyEvent

Triggered when the document is modified, requiring it to be saved.

Parameter	Description	Attributes	Attribute description	Values
isDirty	Displays whether the document needs to be saved.	-	-	`true/false`

Post Message Functions

If signoSign/Universal is called in an iFrame from an enclosing application, there are a number of publicly documented event types that can be called via postMessage.

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

        
            iframe = document.getElementById("iframe");
            iframe.contentWindow.postMessage({
                eventType: "saveDocument"
            }, targetOrigin);

The Viewer provides the following event types:

Event type

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.

Parameter	Description	Values
pageNumber	The number of the page to be displayed	`Integer > 0`

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:

JavaScript

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 (obsolete)

This interface is considered obsolete as of version 3.25.0. This function is replaced by the Post Message API.

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 behavior 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.

JavaScript

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 localized message text.	-	-	`String`
MessageKey	The key value under which the localized message can be found in the locales.	-	-	`String`

SSUSignaturePerformedEvent

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

Parameter	Description	Attributes	Attribute description	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 description	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 synchronized 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 description	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 canceled.
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`

General information

Cross-origin resource sharing

Cookies

postMessage interface

Events

SSUMessageEvent

SSUSignaturePerformedEvent

SSUDocumentSavedEvent

SSUUpdateFormFieldsEvent

SSUPadOpenedEvent

SSUPadClosedEvent

SSUPadStateChangedEvent

SSUSignatureStartEvent

SSUFormFieldFocusEvent

SSUDocumentLoadedEvent

SSUPageNumberChangeEvent

SSUIsDirtyEvent

Post Message Functions

Public JavaScript functions

JavaScript events (obsolete)

SSUMessageEvent

SSUSignaturePerformedEvent

SSUDocumentSavedEvent

SSUUpdateFormFieldsEvent

SSUPadOpenedEvent

SSUPadClosedEvent

SSUPadStateChangedEvent

SSUSignatureStartEvent

SSUFormFieldFocusEvent

SSUDocumentLoadedEvent

SSUPageNumberChangeEvent