# 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
# 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
# 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>