# Personalise the web UI

Documents are signed in our web UI. Learn how to theme it, read web messages, and more.

# Theming

# Play with different themes

To see examples of themes visit our theme preview page (opens new window).

# Different ways to theme your app

Under your account in the Signicat dashboard you can choose to set up a default theme for your account. The default theme will be used unless you override it in the create document API request. You will find this option under Settings API → Override signature settings
You can use the API as explained below to have a different theme for each signer on a document.

# Theme options

Property	What it does
colorTheme	Themes the buttons and icons
themeMode	Choose between a dark or a light theme. If you are using a dark background colour you should set this to Dark.
spinner	Choose between a set of loading spinners
topBar	backgroundColor
backgroundColor	Set a background colour for the app. Both hexadecimal and html colours are accepted.

TIP

It might be a good idea to hide the topbar when in an iframe.

# Theming by API

Include the desired theming options per signer when creating the document.

# Request

POST https://api.signicat.io/signature/documents

Request sample

{
  ....
  "signers": [{
    "ui": {
      "styling": {
        "colorTheme": "Black",
        "themeMode": "Dark",
        "backgroundColor": "#443232",
        "topBar": "Visible"
      }
    }	
  }]
  .....			
}

# Result

click-to-zoom

# Dialogs

In our signature API you can include dialogs with information for the signer. You can set up dialogs that will be displayed before and/or after the document is signed. In the dialog before signing you can also include a checkbox stating that the signer has understood the text.

# Example request

The dialogs object is placed under signers.ui.dialogs

POST https://api.signicat.io/signature/documents

Request sample

{
    ...
    signers: [
        {
            ...
            "ui": {
                "dialogs": {
                  "before": {
                    "useCheckBox": true,
                    "title": "Good luck",
                    "message": "Please read the contract on the following pages carefully. Pay some extra attention to paragraph 5."
                  },
                  "after": {
                    "title": "Thank you for your signature",
                    "message": "We will contact you when we have processed the signed contract."
                  }
            ...
        } 
    ],
    ...
}

# Screenshots

click-to-zoom

# Session timeouts

When a signer clicks on a link to sign a document, they have a time limit to complete the operation.

The session will have a lifetime of 20 minutes if the signer is inactive, if the signer is active in the signature app however, the session token will be renewed 20 more minutes.

The token also has a maximum lifetime of [x] minutes regardless if the user is active or not.

# Web messages

If specified, we post web messages on important events in the signature app.

# Web message structure

The webmessage object we send has this structure. Some of the messages include a payload.

{
    "type": "spinner_on",
    "payload" : undefined
}

# Available messages

type	Payload included
outdated_browser*
app_started**	{ "documentId": "The doc id" }
document_expired	{ "documentId": "The doc id" }
eid_selected	Selected eid (signature method)
document_read***	{ "documentId": "The doc id" }
language_changed	Selected language
spinner_on
spinner_off
user_canceled	{ "documentId": "The doc id" }
sign_success	{ "documentId": "The doc id" }
sign_error	{"errorCode": "Error code if it exists", "errorMessage": "Error message if it exists", "eidErrorCode": "Selected signature method native error code if exists", "eidErrorMessage": "Selected signature method native error code if exists", "documentId": "The doc id" }
already_signed	{ "documentId": "The doc id" }

*The outdated_browser webmessage means that the user is using an old browser that may not work with the signature application. The browser needs to support postMessage to be able to receive this webmessage.

**The app may not start if the browser is too old, you can check for the outdated_browser event to catch this error.

***Only when using internal doc viewer in app.

# Step 1: create request

Include the domain of the site that is hosting the signature app in an iframe. The domain is needed for our csp policy and for webmessaging.

POST https://api.signicat.io/signature/documents

Request sample

{
    ...
    "signers":    [{    
        ...
        "redirectSettings":    {
            "redirectMode": "iframe_with_webmessaging",
            "domain": "example.com",
        } 
        ...   
    ]
    ...
},

Note

If you use nested iframes, you need to include all domains, separated by spaces. The receiver of the web messages has to be the last domain in your list.

# Step 2: Read the web messages

Here is a very simple approach to read them with javascript:

<script>
  window.addEventListener("message", receiveMessage, false);

  function receiveMessage(event) {
   if (event.origin === 'https://sign.idfy.io' || event.origin === 'https://sign-test.idfy.io') {           
      var data = JSON.parse(event.data);  
      var type = data.type;
      var payload = data.payload;      
    }
  }

</script>

← How to retrieve files Extra information and addons →