SignBook v3

The SignBook is the customer interface that allows the user to complete the subscription process. It is a web page hosted by Trust and Sign.

This page should be integrated into a wraparound page in the form of an iFrame in order to be able to manage the entire life cycle of the file.

Our solution supports the two latest versions of the main browsers: Chrome (including on Android), Safari (including on IOS), Firefox, Samsung Browser (on Android), and Edge.

Some of our customers use our SignBook interface in webviews for mobile applications developed in-house.

We know that during your integration, you may encounter certain difficulties that are specific to your information system. Our teams cannot intervene in this area.

Nevertheless, to help your development teams, we'd like to share with you some of our customer feedback on how we've been able to resolve certain malfunctions.

Mobile application webviews are not managed by our teams and remain outside the scope of Namirial support.

Feedback: see Mobile Webview troubleshooting

SignBook integration

For permission reasons, access to the camera and microphone from the iframe (face match functionality) requires the use of an https wrapper page, and to specifically authorise these accesses in the attributes of the attributes of the iframe element: allow="microphone *; camera *"

From now on it is no longer necessary to put the URL in the iframe, it will be built and filled in automatically using the initialization script.

To load the SignBook page correctly and identify the client file using the accessToken, the page will require the following three elements in the production environment:

The iframe element

<iframe id="signbook" scrolling="no" frameBorder="no" width="100%" allow="microphone *; camera *"></iframe>

The Signbook script

<script src="https://api.ekeynox.net/contract/signbook/v3/script/signbook.js"></script>

The initialization script

<script type="text/javascript">
    window.onload = function () {
        var signbook = new NthSignbook({
            iframeSelectorId: 'signbook',
            url: 'https://api.ekeynox.net/contract/signbook/signbook.html',
            options: {
                renderMode: 'pretty'
            },
        });
    }
</script>

Example in integration environment:

<iframe id="signbook" scrolling="no" frameBorder="no" width="100%" allow="microphone *; camera *"></iframe>
<script src="https://integration-api.ekeynox.net/contract/signbook/v3/script/signbook.js"></script>
<script type="text/javascript">
    window.onload = function () {
        var signbook = new NthSignbook({
            iframeSelectorId: 'signbook',
            url: 'https://integration-api.ekeynox.net/contract/signbook/signbook.html',
            options: {
                renderMode: 'pretty'
            }
        });
    }
</script>

Note the difference in the domain name: api.ekeynox.net vs integration-api.ekeynox.net :

• https://integration-api.ekeynox.net should be replaced by : https://preprod-api.ekeynox.net for pre-production
  • https://api.ekeynox.net for production

In the rest of the document, the domain name of the production environment will be used.

WARNING: The use of the La Poste Digital Identity (L'IN) requires the integration of the signbook.js script as well as its initialization script!

Distinction of participants

Depending on the information sent when the file was created, there may be one or more participants. Each participant has a unique access token. For example, to display the journey of the participant whose accessToken is 20140917_7HJOLUbtlKET2iQwBGtN7QkkzFgg2r, simply put the token parameter in the URL of your wrapper page like this

https://monsite/index.html?token=20140917_7HJOLUbtlKET2iQwBGtN7QkkzFgg2r&renderMode=pretty

it is also possible to pass this parameter through the javascript of your wrapper page as follows

<script type="text/javascript">
    window.onload = function () {
        var signbook = new NthSignbook({
            iframeSelectorId: 'signbook',
            url: 'https://api.ekeynox.net/contract/signbook/signbook.html',
            options: {
                renderMode: 'pretty'
            },
            token: '20140917_7HJOLUbtlKET2iQwBGtN7QkkzFgg2r'
        });
    }
</script>

So the URL that will be automatically generated and placed in the iframe will be :

  https://api.ekeynox.net/contract/signbook/signbook.html?token=20140917_7HJOLUbtlKET2iQwBGtN7QkkzFgg2r&renderMode=pretty

Delegation for submission of supporting documents

It is possible to have another delegated participant submit a participant's documents (this is only possible if it is not a (this is only possible if it is not a mandatory pre-signature voucher used for identification). The submission of documents is done by the delegate, on behalf of the participant defined by the primary accessToken. The delegated participant must be a member of the same folder as the main participant.

To start the signbook with a delegated participant, you must add the delegateeToken option to the initialization script as follows option to the initialization script as follows:

<script type="text/javascript">
    window.onload = function () {
        var signbook = new NthSignbook({
            iframeSelectorId: 'signbook',
            url: 'https://api.ekeynox.net/contract/signbook/signbook.html',
            options: {
                delegateeToken: 'token_of_the_delegate',
                renderMode: 'pretty'
            },
        });
    }
</script>

the URL that will be automatically generated and placed in the iframe will be :

  https://api.ekeynox.net/contract/signbook/signbook.html?token=20140917_7HJOLUbtlKN7QkkzFgg2r2&delegateeToken={token_of_delegate}&renderMode=pretty

It is of course also possible to pass this parameter directly from the URL of your wrapper page by simply adding the parameter as follows:

https://monsite/index.html?token=20140917_7HJOLUbtlKET2iQwBGtN7QkkzFgg2r&delegateeToken={delegate_token}&renderMode=pretty

The delegation operation is traced in the reporting file.

Signbook display requirements

For a better user experience on mobile, it is recommended not to put margins around the iframe because on mobile the minimum width of the SignBook to respect is 320px.

Display the new version of the Signbook for supporting documents

It is possible to display the new version of the credentials page, to do so, you just have to add the parameter renderMode=pretty

WARNING: The old page being deprecated, this mode will be activated by default in a future version. Please activate it now.

Just add the renderMode option as follows:

<script type="text/javascript">
    window.onload = function () {
        var signbook = new NthSignbook({
            iframeSelectorId: 'signbook',
            url: 'https://api.ekeynox.net/contract/signbook/signbook.html',
            options: {
                renderMode: 'pretty'
            },
        });
    }
</script>

it is also possible to pass this parameter directly from the URL of your wrapper page by adding the following value after your URL:

&renderMode=pretty

the URL that will be automatically generated and placed in the iframe will be :

https://api.ekeynox.net/contract/signbook/signbook.html?token=20140917_7HJOLUbtlKN7QkkzFgg2r2&renderMode=pretty

This mode cannot be combined with the tiny mode.

SignBook display in reduced mode for supporting documents

It is possible to display the credentials page in the SignBook in reduced mode, to do this, you just need to add the parameter renderMode=tiny

Just add the renderMode option as follows:

<script type="text/javascript">
    window.onload = function () {
        var signbook = new NthSignbook({
            iframeSelectorId: 'signbook',
            url: 'https://api.ekeynox.net/contract/signbook/signbook.html',
            options: {
                renderMode: 'tiny'
            },
        });
    }
</script>

it is also possible to pass this parameter directly from the URL of your wrapper page by adding the following value after your URL:

&renderMode=tiny

the URL that will be automatically generated and placed in the iframe will be :

https://api.ekeynox.net/contract/signbook/signbook.html?token=20140917_7HJOLUbtlKN7QkkzFgg2r2&renderMode=tiny

This mode cannot be combined with the pretty mode.

Single page display

It is possible to display only one of the default tabs (Identification, Signature and Attachments) to the user when they complete their journey, by adding a displayedPages query parameter. This can take several values, such as identity, signature or attachments, or even several. For example &displayedPages=attachments,signature, the default behaviour of the Signbook will be kept. If only one of these two values is entered, the Signbook will only display the corresponding tab and the end user will be automatically directed to it. The other tab will then be disabled.

<script type="text/javascript">
    window.onload = function () {
        var signbook = new NthSignbook({
            iframeSelectorId: 'signbook',
            url: 'https://api.ekeynox.net/contract/signbook/signbook.html',
            options: {
                displayedPages: 'signature',
                renderMode: 'pretty'
            },
        });
    }
</script>

it is also possible to pass this parameter directly from the URL of your wrapper page by adding the following value after your URL:

&displayedPages=signature

the URL that will be automatically generated in the iframe will be :

  https://api.ekeynox.net/contract/signbook/signbook.html?token=20140917_7HJOLUbtlKN7QkkzFgg2r2&displayedPages=signature&renderMode=pretty

Filter the display on the categories of the receipts

SignBook offers the possibility of filtering the credentials page according to credential categories. For example, you can display only identity documents by using a parameter like this:

<script type="text/javascript">
    window.onload = function () {
        var signbook = new NthSignbook({
            iframeSelectorId: 'signbook',
            url: 'https://api.ekeynox.net/contract/signbook/signbook.html',
            options: {
                documentCategories: 'ID_DOCUMENT', // to display only the credentials
                renderMode: 'pretty'
            },
        });
    }
</script>

it is also possible to pass this parameter directly from the URL of your wrapper page by adding the following value after your URL:

&documentCategories=ID_DOCUMENT

Note that this parameter can take several values separated by commas, e.g. to filter on identity documents and income documents you just have to put :

documentCategories=ID_DOCUMENT,INCOME_DOCUMENT

Here is the list of supported credential categories: - ID_DOCUMENT: Identity document - BANKING_DOCUMENT : Bank document - ADDRESS_DOCUMENT : Address proof - INCOME_DOCUMENT : Proof of income - UNDEFINED : Other document

Finally, please note that the value is case insensitive.

Displaying the SignBook in a given language

It is possible to force the Signbook to be displayed in a language defined from the following list: - French (fr) - English (en) - Italian (it) - Spanish (es) - German (de) - Romanian (ro) - Croatian (hr). - Portuguese (pt) - Dutch (nl)

to do this, simply add the lang parameter as follows:

<script type="text/javascript">
    window.onload = function () {
        var signbook = new NthSignbook({
            iframeSelectorId: 'signbook',
            url: 'https://api.ekeynox.net/contract/signbook/signbook.html',
            options: {
                lang: 'en',
                renderMode: 'pretty'
            },
        });
    }
</script>

If this parameter is not supplied then the language defined in the path product will be loaded.

It is also possible to pass this parameter directly from the URL of your wrapper page by adding the following value after your URL

&lang=en

the URL that will be automatically generated in the iframe will be:

  https://api.ekeynox.net/contract/signbook/signbook.html?token=20140917_7HJOLUbtlKN7QkkzFgg2r2&renderMode=pretty&lang=fr

Redefine the link back to the encompassing page for the SignBook

Some SignBook features require you to know the starting link of the encompassing page in order to use it as a return link at the end of certain paths (callback url).

For example, if the user prefers to perform his identity verification with facial recognition using his smartphone, he can ask Signbook to send him the page of the journey by SMS, and at the end of his identity verification on mobile, he wants to be able to automatically return to his initial path.

For this the default link that will be used is the URL of the wrapper page, however you can redefine this value as follows:

<script type="text/javascript">
    window.onload = function () {
        var signbook = new NthSignbook({
            iframeSelectorId: 'signbook',
            url: 'https://api.ekeynox.net/contract/signbook/signbook.html',
            options: {
                callbackURL: 'https://initial-page-to-redirect',
                renderMode: 'pretty'
            },
        });
    }
</script>

Modify the launch behaviour of video identification

By default, when the user clicks on the button to begin video identity verification, a new Popup browser window opens. You can modify this behaviour to obtain a redirect that will replace the current page directly with the video identification page.

To do this, simply add the vidRequestMode parameter to the SignBook options. This parameter can take either redirect or popup as possible values, with popup as the default.

Below is an example of how to use this parameter:

<script type="text/javascript">
    window.onload = function () {
        var signbook = new NthSignbook({
            iframeSelectorId: 'signbook',
            url: 'https://api.ekeynox.net/contract/signbook/signbook.html',
            options: {
                vidRequestMode: 'redirect', // redirect or popup
                renderMode: 'pretty'
            },
        });
    }
</script>

It is also possible to pass this parameter directly from the URL of your wrapper page by adding the following value after your URL

&vidRequestMode=redirect

the URL that will be automatically generated in the iframe will be:

  https://api.ekeynox.net/contract/signbook/signbook.html?token=20140917_7HJOLUbtlKN7QkkzFgg2r2&renderMode=pretty&vidRequestMode=redirect

Modify the launch behaviour of Powens bank flow

Recommended option for mobile. By default, when the user clicks on the button to begin the Powens bank flow to submit a banking document, a new Popup browser window opens. You can modify this behaviour to obtain a redirect that will replace the current page directly with the video identification page.

To do this, simply add the bankAccountMode parameter to the SignBook options. This parameter can take either redirect or popup as possible values, with popup as the default.

Below is an example of how to use this parameter:

<script type="text/javascript">
    window.onload = function () {
        var signbook = new NthSignbook({
            iframeSelectorId: 'signbook',
            url: 'https://api.ekeynox.net/contract/signbook/signbook.html',
            options: {
                bankAccountMode: 'redirect', // redirect or popup
                renderMode: 'pretty'
            },
        });
    }
</script>

It is also possible to pass this parameter directly from the URL of your wrapper page by adding the following value after your URL

&bankAccountMode=redirect

the URL that will be automatically generated in the iframe will be:

  https://api.ekeynox.net/contract/signbook/signbook.html?token=20140917_7HJOLUbtlKN7QkkzFgg2r2&renderMode=pretty&bankAccountMode=redirect

Automatic reload of the SignBook once the client file has been unblocked

By default, when the client file is suspended and requires the intervention of an operator, a message is displayed to the user either via SignBook or via the parent page. But once the client file is unblocked, it is up to the customer to restore the user flow so that the participant can resume and continue his or her journey, either by reloading the SignBook iframe using WebHook notifications, for example, or simply by notifying the user by email and including the path link.

We're introducing a new feature that allows SignBook to reload automatically after an unblock. To do this, simply add the autoReload parameter to the SignBook options. This parameter has the following possible values: either true or false, with false as the default.

Below is an example of how to use this parameter:

<script type="text/javascript">
    window.onload = function () {
        var signbook = new NthSignbook({
            iframeSelectorId: 'signbook',
            url: 'https://api.ekeynox.net/contract/signbook/signbook.html',
            options: {
                autoReload: 'true', // reload the SignBook content after unblocking client file
                renderMode: 'pretty'
            },
        });
    }
</script>

It is also possible to pass this parameter directly from the URL of your wrapper page by adding the following value after your URL

&autoReload=true

the URL that will be automatically generated in the iframe will be:

  https://api.ekeynox.net/contract/signbook/signbook.html?token=20140917_7HJOLUbtlKN7QkkzFgg2r2&renderMode=pretty&autoReload=true

Interactions with the SignBook

The SignBook communicates with the wrapper page by sending it serialized JSON events in the form of a string.

These events can be divided into four categories, each with a different purpose:

• user events: these describe the user's interactions with the SignBook interface (see User Events)

• Client file events: these give information about the client file, mainly its status and its transition from one status to another, or the list of submitted receipts. It occurs when the client file has loaded for the first time on arrival at the SignBook or reloaded following an event (acceptance, suspension, rejection, submission, etc.), suspension, rejection, submission, etc.) (see Client File Events)

• error events: these alert the enclosing page to the fact that an error has occurred (see Error Events)

• SignBook display events: these allow the encompassing page to adapt to visual changes in the of the SignBook (see Display Events)

• events indicating that the user has clicked the exit and return button

Important note: Event management as in Signbook V1 is deprecated but will remain supported until Q1 2017.

It is possible to intercept these events by providing your own business javascript functions using the following options:

• onUserEventMessage for user events.
• onClientFileEventMessage for client file events.
• onErrorEventMessage for error events
• onDisplayEventMessage for SignBook display events.
• onExitEventMessage for the event triggered when the participant leaves the SignBook to return later.

The configuration is done as follows:

<script type="text/javascript">
    window.onload = function () {
        var signbook = new NthSignbook({
            iframeSelectorId: 'signbook',
            url: 'https://api.ekeynox.net/contract/signbook/signbook.html',
            options: {
                renderMode: 'pretty'
            },
            onUserEventMessage: onUserEventMessageFn,
            onClientFileEventMessage: onClientFileEventMessageFn,
            onErrorEventMessage: onErrorEventMessageFn,
            onDisplayEventMessage: onDisplayEventMessageFn,
            onExitEventMessage: onExitEventMessageFn,
        });
    }
</script>

Enable / disable message listening

It is possible to disable listening to messages from the SignBook in the wrapper page, This can be useful, for example, when the iframe is taken down. To do this, simply call the destroy() function like this

<script type="text/javascript">

    var signbook = new NthSignbook({...});
    ...
    signbook.destroy(); // stop listening to messages

    signbook.attachEventListener(); // re-enable message listening

</script>

Example of a complete bounding page

<!DOCTYPE html>
<html>
<head>
    <title> Mon parcours client </title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
    <link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/normalize/5.0.0/normalize.min.css"/>
    <style>
        #container {
            padding: 20px;
            margin: 0 auto;
        }
        #message-container {
            display: none;
            width: 100%;
            text-align: center;
            margin: 200px auto;
        }
        #iframe-wrapper {
            width: 100%;
            overflow: hidden;
        }
    </style>
</head>
<body>

<div id="container">
    <header></header>
    <div id="iframe-wrapper">
        <iframe id="signbook" width="99%" scrolling="no" frameBorder="no" allow="microphone *; camera *"></iframe>
    </div>
    <div id="message-container">
        <h4 id="message-title"></h4>
        <p id="message-text"></p>
    </div>
    <footer></footer>
</div>

<script src="https://api.ekeynox.net/contract/signbook/v3/script/signbook.js"></script>

<script type="text/javascript">

    var MESSAGE_TITLES = {
        'EXIT': "A bientôt !",
        'SUSPENDED': "Pièces justificatives en cours de contrôle",
        'FINALIZED': "Dossier complet",
        'WAITING': "Dossier en cours de validation",
        'ACCEPTED': "Félicitations !",
        'REJECTED': "Désolé"
    };

    var MESSAGE_TEXTS = {
        'EXIT': "Vous pouvez revenir quand vous le souhaitez compléter votre dossier.",
        'SUSPENDED': "Une ou plusieurs des pièces que vous avez soumises sont en cours d'examen par nos opérateurs. Merci de revenir plus tard.",
        'FINALIZED': "Votre dossier est désormais complet, nous vous recontacterons quand nous l'aurons examiné.",
        'WAITING': "Votre dossier est en cours d'examen.",
        'ACCEPTED': "Votre dossier a été accepté.",
        'REJECTED': "Votre dossier a été refusé."
    };

    var ERROR_TEXTS = {
        'BROWSER_NOT_SUPPORTED': "Désolé, ce navigateur n'est pas supporté, veuillez utiliser Chrome, Firefox, Safari, IE10+, Edge ou Opera."
    };

    var GENERIC_ERROR_TEXT = "Nos serveurs sont en cours de maintenance, merci de revenir plus tard.";

    /**
     * Show a message instead of the SignBook
     * @param title
     * @param text
     */
    function showMessage(title, text) {
        document.getElementById('iframe-wrapper').style.display = 'none';
        document.getElementById('message-container').style.display = 'block';
        document.getElementById('message-title').innerHTML = title;
        document.getElementById('message-text').innerHTML = text;
    }

    function onUserEventMessageFn(event) {
        // All user actions => used by web analytics libraries like Google Analytics
        console.log("user event : " + event.action);
    }

    function onClientFileEventMessageFn(event) {
        // Event coming from eKeynox SaaS with data concerning the state of the client file
        console.log("client file state : " + event.state);

        if ((event.changedState &&
                (event.changedState.from === 'PENDING' && (event.changedState.to === 'WAITING' || event.changedState.to === 'ACCEPTED'))) ||
                (event.participantState === 'WAITING')) {
            showMessage(MESSAGE_TITLES['FINALIZED'], MESSAGE_TEXTS['FINALIZED'])
        } else {
            if (event.state !== 'PENDING') {
                showMessage(MESSAGE_TITLES[event.state], MESSAGE_TEXTS[event.state]);
            }
        }
    }

    function onExitEventMessageFn(event) {
        showMessage(MESSAGE_TITLES['EXIT'], MESSAGE_TEXTS['EXIT']);
    }

    function onErrorEventMessageFn(event) {
        // Errors detected by the SignBook (server errors, invalid state, unsupported browser, etc.)
        if (event.cause === 'REJECTED_STATE' || event.cause === 'ACCEPTED_STATE'
                || event.cause === 'SUSPENDED_STATE' || event.cause === 'WAITING_STATE') {
            // Do not deal with these "errors", this is just for backwards compatibility purpose...
            return;
        }
        showMessage('Erreur', (ERROR_TEXTS[event.cause] ? ERROR_TEXTS[event.cause] : GENERIC_ERROR_TEXT) + "(" + event.cause + ")");
    }

    /**
     * Called on page loaded
     */
    window.onload = function () {
        var signbook = new NthSignbook({
            iframeSelectorId: 'signbook',
            url: 'https://api.ekeynox.net/contract/signbook/signbook.html',
            options: {
                renderMode: 'pretty'
            },
            onUserEventMessage: onUserEventMessageFn,
            onClientFileEventMessage: onClientFileEventMessageFn,
            onExitEventMessage: onExitEventMessageFn,
            onErrorEventMessage: onErrorEventMessageFn,
        });
    }

</script>

</body>
</html>

Note: in order for the component to fit in a tablet layout, it is recommended to specify the width of the iframe as a percentage.

User events

These events can typically be retrieved by the wrapper page for use by an analytics tool such as Google Analytics. The type of these events is userEvent.

Any userEvent will have the following properties:

• action ...
• context: context in which the user action was executed This is an object containing the following keys:
  • userIndex : participant number (the first participant has the number 1)
  • page : signature / attachments / maintenance ...
  • The other keys of the context depend on the action (see the table below)

Action	Description	Contextual information specific to the action	Example
ACTION_IDENTIFICATION_ENTERING_MOBILE_WAY	At the start of FAST or MAX identity verification, the user clicks to continue on mobile.	recorderMode (Type of video identification FAST or MAX)	{ type: "userEvent", action: "ACTION_IDENTIFICATION_ENTERING_MOBILE_WAY", context: {type: 'VIDEO_IDENTIFICATION', recorderMode: 'FAST', userIndex: 1, page: 'identity'}}
ACTION_IDENTIFICATION_USING_QRCODE	At the start of FAST or MAX identity verification, the user clicks to get a QRCode	recorderMode (Type of video identification FAST or MAX)	{ type: "userEvent", action: "ACTION_IDENTIFICATION_USING_QRCODE", context: {type: 'VIDEO_IDENTIFICATION', recorderMode: 'FAST', userIndex: 1, page: 'identity'}}
ACTION_IDENTIFICATION_USING_SMS	At the start of FAST or MAX identity verification, the user clicks to receive an SMS.	recorderMode (Type of video identification FAST or MAX)	{ type: "userEvent", action: "ACTION_IDENTIFICATION_USING_SMS", context: {type: 'VIDEO_IDENTIFICATION', recorderMode: 'FAST', userIndex: 1, page: 'identity'}}
ACTION_IDENTIFICATION_LEAVING_MOBILE_WAY	At the start of FAST or MAX identity verification, the user returns to the main page.	recorderMode (Type of video identification FAST or MAX)	{ type: "userEvent", action: "ACTION_IDENTIFICATION_LEAVING_MOBILE_WAY", context: {type: 'VIDEO_IDENTIFICATION', recorderMode: 'FAST', userIndex: 1, page: 'identity'}}
ACTION_IDENTIFICATION_START	Starting FAST or MAX video identification process	recorderMode (Type of video identification FAST or MAX)	{ type: "userEvent", action: "ACTION_IDENTIFICATION_START", context: {type: 'VIDEO_IDENTIFICATION', recorderMode: 'FAST', userIndex: 1, page: 'identity'}}
SELECT_CONTRACT_TAB	In multi-contract mode, select a contract for viewing	contract (contract name defined in Workflow)	{ type: "userEvent", action: "SELECT_CONTRACT_TAB", contract: "contract_name" }
ACTION_ACCEPT_GDPR	Consentement RGPD		{ type: "userEvent", action: "ACTION_ACCEPT_GDPR" }
INTERNAL_IDENTITY_STEP	Informs that the user is progressing through the identity verification process (FaceMatch Photo)	page (targeted step page index)	{type: "userEvent", action: "INTERNAL_IDENTITY_STEP", page: "step-0"}
SELECT_DOCUMENT_TYPE	Selection of the type of document that will be uploaded	attachmentId documentType (ID_CARD or PASSPORT for example)	{ type: "userEvent", action: "SELECT_DOCUMENT_TYPE", attachmentId: "attachment_1", documentType: "ID_CARD" }
SELECT_FILE	Selection of file to be uploaded	attachmentId documentType	{ type: "userEvent", action: "SELECT_FILE", attachmentId: "attachment_1", documentType: "ID_CARD" }
ADD_FILE	Add an additional file to upload	attachmentId documentType	{ type: "userEvent", action: "ADD_FILE", attachmentId: "attachment_1", documentType: "ID_CARD" }
CAPTURE_FILE	An image has been captured and added for sending the document.	attachmentId documentType	{ type: "userEvent", action: "CAPTURE_FILE", attachmentId: "attachment_1", documentType: "ID_CARD" }
REMOVE_FILE	Delete an additional file to upload	attachmentId documentType	{ type: "userEvent", action: "REMOVE_FILE", attachmentId: "attachment_1", documentType: "ID_CARD" }
UPLOAD	Send documents	attachmentId documentType	{ type: "userEvent", action: "UPLOAD", attachmentId: "attachment_1", documentType: "ID_CARD" }
ACTION_ACCEPT_EXTERNAL_CONSENTS	Consentement pour émission du certificat lié à la signature qualifiée		{ type: "userEvent", action: "ACTION_ACCEPT_EXTERNAL_CONSENTS" }
CHECK_CLAUSE	Selection of a clause from the consent protocol	clauseId (clause identifier as defined in Workflow) checked (true / false after click)	{ type: "userEvent", action: "CHECK_CLAUSE", clauseId: "clause_1", checked: true }
DOWNLOAD_DOCUMENT_BEFORE	Downloading a document before signing (not available in the new signature page)		{ type: "userEvent", action: "DOWNLOAD_DOCUMENT_BEFORE" }
DOWNLOAD_SIGNED_DOCUMENT	Downloading a document after signing (not available in the new signature page)		{ type: "userEvent", action: "DOWNLOAD_SIGNED_DOCUMENT" }
CHECK_CONSENT_DOWNLOAD_DOCUMENT_BEFORE	User agrees to have downloaded all required documents before signing		{ type: "userEvent", action: "CHECK_CONSENT_DOWNLOAD_DOCUMENT_BEFORE" }
CHECK_CONSENT_DOWNLOAD_SIGNED_DOCUMENT	User agrees to have downloaded all required documents after signing		{ type: "userEvent", action: "CHECK_CONSENT_DOWNLOAD_SIGNED_DOCUMENT" }
VALIDATE_DOWNLOAD_DOCUMENT_BEFORE	Validation of uploading a document before signing (not available in the new signature page)		{ type: "userEvent", action: "VALIDATE_DOWNLOAD_DOCUMENT_BEFORE" }
VALIDATE_DOWNLOAD_SIGNED_DOCUMENT	Validation of uploading a document after signing (not available in the new signature page)		{ type: "userEvent", action: "VALIDATE_DOWNLOAD_SIGNED_DOCUMENT" }
FOCUS_ON_OTP	The cursor is in the OTP input field (not available in the new signature page)		{ type: "userEvent", action: "FOCUS_ON_OTP" }
TYPE_OTP	Entering an OTP character		{ type: "userEvent", action: "TYPE_OTP" }
OPEN_NEW_OTP_DIALOG	Opening the dialog box to request a new OTP (not available in the new signature page)		{ type: "userEvent", action: "OPEN_NEW_OTP_DIALOG" }
CLOSE_NEW_OTP_DIALOG	Closing the dialog box for requesting a new OTP (not available in the new signature page)		{ type: "userEvent", action: "CLOSE_NEW_OTP_DIALOG" }
REQUEST_NEW_OTP	Request for a new OTP		{ type: "userEvent", action: "REQUEST_NEW_OTP" }
SIGN	Click on the button to execute the signature		{ type: "userEvent", action: "SIGN" }
REFUSE_SIGNATURE	Click on the confirmation button to refuse the signature		{ type: "userEvent", action: "REFUSE_SIGNATURE" }
EXIT_AFTER_SUSPENSION	Click on "Come back later" in the dialog box that appears after the file has been suspended		{ type: "userEvent", action: "EXIT_AFTER_SUSPENSION" }
EXIT	Click on "Come back later"		{ type: "userEvent", action: "EXIT" }
FINALIZE	Click on "Submit Clientfile"		{ type: "userEvent", action: "FINALIZE" }

Important note: some events in the Signbook V1 have been deleted (OPEN_DOCUMENT_UPLOAD_DIALOG, CLOSE_DOCUMENT_UPLOAD_DIALOG, GO_TO_COSIGNER_SIGNATURE_PAGE).

Customer file events

These events can be retrieved by the encompassing page to for example to display a contextualised message to the user.

The type of these events is clientFileEvent.

Any clientFileEvent will have the following properties:

• state : the state of the file

• cause: cause of rejection when the file is in the "REJECTED" status (see appendix list of causes of rejection)

• participantState: status of the participant, is "PENDING" if the participant has not completed the file, "WAITING" if the file has been completed and "DONE" if the file has been accepted or rejected

• changedState: contains the keys from and to corresponding respectively to the previous state of the file and the new state when the file changes state

• context: contains additional information about the file, the information can be

  • type: name or topic of additional information (available type: signature)

  • status : ok if the operation was successful, ko otherwise

  • owner: identifier of the type of participant who triggered the operation

  • userIndex: participant number (the first participant has the number 1)

  • attachmentId: document identifier in the case of a submission event

  • submittedAttachments: identifiers of all documents already submitted in the client file

  • mandatoryAttachmentsToSubmit: identifiers of mandatory documents not yet submitted in the client file

  • optionnalAttachmentsToSubmit: identifiers of optional documents not yet submitted in the client file

  • signatureState : status of the signature task if there is a signature in the client file with the following possible value

    • TODO : the signature is to be made
    • TO_RETRY : the signature has to be redone, after reopening the file
    • RUNNING : the signature is being processed
    • UNAVAILABLE : the signature is not available at the moment
    • OK : the signature is successfully completed
    • KO : the signature failed

  • liveChekState : LiveCheck task status (manual check by Netheos Services operators) if applicable with possible value see task status list below

    • TODO : manual check is to be done
    • TO_RETRY : manual check to be redone, after reopening the client file
    • RUNNING : manual check is in progress
    • OK : manual check is successful
    • KO : unfavourable verdict of the manual check

  • identitySubmissionDone : indicates whether the user path for identity verification is complete, possible values true | false

  • identification : Lists the details of the identity verification tasks, for example in the case of a photo FaceMatch then there will be two tasks one for the submission of the ID and the second for the selfie.

  • nextStep : The next action to be taken by the participant, the possible values are

    • IDENTITY : the next action is the verification of the participant's identity
    • SIGNATURE : the next action is the signing
    • DOCUMENT : the next action is the submission of a receipt
    • UNAVAILABLE : the next action is not available

context type	Description	Example
attachmentSubmission	A submission of a part has just been made	{ type: "clientFileEvent", state: "PENDING", participantState: "PENDING", context: { type: "attachmentSubmission", status: 'ok', owner: "SIGNER", taskId: "1_1", attachmentId: "attachment_1", submittedAttachments: ["attachment_1"], mandatoryAttachmentsToSubmit: ["attachment_2"], optionalAttachmentsToSubmit: [] } }
signature	The signature operation has just been performed	{ type: "clientFileEvent", state: "PENDING", participantState: "PENDING", context: { type: "signature", status: 'ok', owner: "SIGN", submittedAttachments: ["attachment_1", "attachment_2"], mandatoryAttachmentsToSubmit: [], optionalAttachmentsToSubmit: [] } }
signatureRefusal	The signature refusal operation has just been performed	{ type: "clientFileEvent", state: "PENDING", participantState: "DONE", context: { type: "signatureRefusal", status: 'ok', owner: "SIGN", submittedAttachments: ["attachment_1", "attachment_2"], mandatoryAttachmentsToSubmit: [], optionalAttachmentsToSubmit: [] } }

Important note: the FINALIZED state in Signbook V1 no longer exists. The equivalent of this state is the change from a PENDING state to a WAITING state or to an ACCEPTED state (if the path is in automatic acceptance) which can be captured by the changedState key.

Full example of clientFileEvent when identity is done and LiveCheck is running before signature:

{
  "type": "clientFileEvent",
  "state": "PENDING",
  "participantState": "PENDING",
  "context": {
    "nextStep": "IDENTITY",
    "submittedAttachments": [],
    "mandatoryAttachmentsToSubmit": [],
    "optionnalAttachmentsToSubmit": [],
    "signatureState": "UNAVAILABLE",
    "liveCheckState": "RUNNING",
    "identification": [
      {
        "type": "DOCUMENT_SUBMISSION",
        "state": "WAITING",
        "taskId": "1_1",
        "attachmentId": "attachment_1"
      },
      {
        "type": "FACE_MATCH",
        "state": "WAITING",
        "taskId": "1_FM_1"
      }
    ],
    "identitySubmissionDone": true
  }
}

Example of clientFileEvent with state change :

{
    type: "clientFileEvent",
    state: "WAITING",
    participantState: "WAITING",
    changedState: {
        from: "PENDING",
        to: "WAITING"
    }
}

Identity Verification Events

When the identity verification (photo or video) is done, an event of type identity is sent to the wrapper page. Here is an example:

event = {
   type: "identity",
   state: "WAITING",
   ok: true
}

And here is an example of javascript code to see this event:

window.addEventListener('message', function(evt){
    var msg = JSON.parse(evt.data);
    if (msg && msg.type === 'identity') {
        console.log('message: ',msg);
    }
}, false);

Error events

These events can be retrieved by the wrapper page to display a contextualised message to the user, for example. The type of these events is errorEvent.

Any errorEvent will have the following properties:

• cause: the cause of the error

Cause	Description	Example
BROWSER_NOT_SUPPORTED	Browser is not supported	{ type: "errorEvent", cause: "BROWSER_NOT_SUPPORTED" }
INVALID_URL	The url to access the client file is incorrect...	{ type: "errorEvent", cause: "INVALID_URL" }
INVALID_STATE	The state of the client file is inconsistent...	{ type: "errorEvent", cause: "INVALID_STATE" }
type: "errorEvent", cause: "BAD_REQUEST" }	BAD_REQUEST	The request is badly formed
SERVER_ERROR	A server error has occurred	{ type: "errorEvent", cause: "SERVER_ERROR" }
SERVER_MAINTENANCE	Service is under maintenance	{ type: "errorEvent", cause: "SERVER_MAINTENANCE" }
type: "errorEvent", cause: "UNKNOWN " }

SignBook display events

These events allow the wrapper to adjust the display of the SignBook. The type of these events is displayEvent.

DisplayEvent have the following properties:

• cause: the cause of the event
• the other information depends on the event

Cause	Description	Additional parameters	Example
heightChanged	The height of the SignBook has changed	height: new height required by the SignBook (in px)	{ type: "displayEvent", cause: "heightChanged", height: "1200" }
pageChanged	The user has changed pages, for example, from the sign-in page to the document submission page. This event can be exploited by the enclosing page to scroll the page up (via iframe.scrollTop = 0)		{ type: "displayEvent", cause: "pageChanged", }
modalPosition	A modal has been displayed on the SignBook, and the parent page needs to scroll to the position of this modal in the page	offsetTop: value of the modal position in the SignBook iframe	{ type: "displayEvent", cause: "modalPosition", "offsetTop": 1423 }

SignBook settings

To achieve full visual integration, it is possible to configure the appearance and texts of the SignBook using the following 3 files:

• custom.css : Formatting (font size, screen colour...) in Cascading Style Sheets (CSS) format ( Default file )
• strings.custom_[lang].json: Setting texts for the chosen language (replace [lang] with the corresponding language code (example: fr or en)). It is advisable to use an appropriate editor (e.g. Notepad++) to modify this file in JSON format ( Default file in French). Please note that this file must be encoded in UTF-8 without BOM.
  • Customisation files available:
    • strings.custom_fr.json: Default file .
    • strings.custom_en.json: English file
    • strings.custom_it.json: Italian file
    • strings.custom_es.json: Spanish file
    • strings.custom_nl.json: Dutch file
    • strings.custom_pt.json: Portuguese file
    • strings.custom_ro.json : Romanian file
    • strings.custom_de.json : German file
    • strings.custom_hr.json : Croatian file
• page.html: corresponds to the wrapping page of the SignBook in HTML format

These files should then be put together in a ZIP archive (whatever the archive is called).

When configuring a contracting path in the administration part of Trust and Sign, this ZIP file will have to be selected in the "SignBook File" field located in the advanced settings in the "General" tab of the path.

Important note: regarding the custom.css and strings.custom_[lang].json files, you should only group together in the ZIP archive the changes you wish to make. For example, if you only want to change one text, the strings.custom_[lang].json file will only contain one key corresponding to this text.

Configuring the texts in the GDPR modal

In the text customisation file, the translation keys to be adjusted to customise the content of the GDPR modal are all preceded by the prefix GDPR_MODAL_*.

Warning: By modifying the texts relating to the GDPR, you assume full responsibility for their legal compliance.

Configuration of the custom.css file

The "custom.css" file is used to configure the display of the SignBook: font layout (size and colour), choice of background colours (tab, window).

Colour codes must be entered in hexadecimal format (e.g. #FFDDEE).

The font families must be filled in according to the "CSS notation" (e.g. "Times New Roman", "Georgia", "Serif").

Property	Default value
Font family	Helvetica, Arial

The colours of the signbook are applied using css classes. Changing the colour code of a class will change the colour of all the elements that share it. The colour classes are divided into three groups:

• font colour classes
• background colour classes (starting with background-)
• border colour classes (starting with border-)

CSS class	Default value	Overview	Type
active-color	#ffffff		font
background-active-color	#5781a1		background
inactive-color	#615d5a		font
background-inactive-color	#bed1e0		background
accent-color	#1f1f1f		font
background-accent-color	#ffffff		background
secondary-color	#615d5a		font
background-secondary-color	#ebebeb		background
border-secondary-color	#ebebeb		border
background-dropzone-color	#f5f5f5		background
border-dropzone-color	#8eacc2		border
background-general-color	#f4f5f9		background
hint-color	#31708f		font
background-hint-color	#ddf2fc		background
border-hint-color	#a2d3de		bodure
alert-color	#a94442		font
background-alert-color	#f2dede		background
border-alert-color	#ebccd1		bodure
help-color	#3c763d		font
background-help-color	#dff0d8		background
border-help-color	#d6e9c6		border

SignBook customisation help screens

Below you'll find information on the various SignBook pages. We've indicated the CSS classes (in blue) for locating the elements to be modified, and the translation keys (in purple) for customising the text.

Identity verification page

Qualified signature page, consents for the certification authority

Signature page

Attachments submission page

Alert page

Customise the display of receipts

You can also change the appearance of the receipt blocks according to their status (pending, submitted, validated, etc.).

A "data-task-state" attribute is available to allow the use of a CSS selector for example. This attribute will take the value of the voucher state:

• TODO (document to be sent)
• WAITING (supporting document sent)
• OK (document sent and file submitted)
• TO_RETRY (document sent but in error, waiting to be resent)

For example, you can decide to hide a block whose part has been successfully sent:

div[data-task-state='WAITING'] {
  display: none;
}

Or decide to display a grey background on already validated parts when reopening:

div[data-task-state='OK'] {
  background: #ccc;
}

Customise the display for the new credentials page

The new interface of the credentials page is based on the .pretty CSS class which is located on the body of the page. So remember to prefix your new CSS rules in the custom.css using the .pretty class

for example to change the background colour of the SignBook

.pretty.background-general-color {
    background-color: #fff;
}

Below is a list of key CSS classes to use if required

New credentials page

Modal for submission of credentials

Error alert mode

Document Capture via the document submission modal

The document capture feature is only available in pretty mode.

Tooltip to choose the source of the document

Loader displayed as long as the access rights to the camera are not accepted

Document capture page of the modal

Document preview page of the modal

Customise the buttons at the bottom of the SignBook page

Action buttons at the bottom of the page can be targeted with CSS selectors using the following appropriate classes:

Button	CSS class to use
Continue	action-continue
Submit file	action-finalize
Back to the previous step (attachments)	action-back-to-attachments
Come back later	action-come-back-later

Setting the appearance of the Video FaceMatch

It is possible to configure the appearance of the FaceMatch video by providing an additional CSS file named custom-video-identification.css to be provided in the SignBook customization ZIP archive.

This CSS file can contain your own CSS, but the recommended method is to use the CSS variables listed below:

List of CSS variables

CSS Variable	Default value	Preview	Description
--nc-branding-logo-image	url('assets/images/v2/LOGO.svg')		branding image shown in first screen
--nc-branding-logo-width	228px		branding image width
--nc-branding-logo-height	66px		branding image height
--nc-font-family	'Quicksand', sans-serif;		global text font
--nc-font-weight	500		font weight for global text
--nc-font-color	#333333		global text color
--nc-font-size	1rem		global font size
--nc-button-active-background	#014AD8		background color for buttons
--nc-button-active-color	#FFFFFF		text color for buttons
--nc-button-disabled-background	rgba(47, 95, 227, 0.25)		background color for disabled buttons
--nc-button-disabled-color	rgba(255, 255, 255, 0.8)		text color for disabled buttons
--nc-button-font-size	16px		text size for buttons
--nc-button-font-weight	bold		font weight for text in buttons
--nc-button-text-transform	uppercase		can be used to make button text appear in uppercase or lowercase
--nc-button-border-radius	8px		border radius size for buttons
--nc-checkbox-container-checked-background	#FFFFFF		checkbox container background color when selected
--nc-checkbox-background	#2F5FE3		background color for checkboxes
--nc-checkbox-checkmark-color	#FAFAFA		checkbox color when selected
--nc-checkbox-border-color	##014AD8		border color of checkbox
--nc-checkbox-width	20px		checkbox width size
--nc-checkbox-height	20px		checkbox height size
--nc-link-color	#014AD8		link text color
--nc-box-background	rgba(1, 74, 216, 0.03)		background color for box panel in first step
--nc-box-border-radius	8px		border radius for box panel in first step
--nc-box-document-type-background	#FFFFFF		background color for item selection in document type step
--nc-box-document-type-border-radius	8px		border radius for item selection in document type step
--nc-progress-bar-background	#014AD8		background color for progress bar in upload step
--nc-validation-color	#1af9b6		colour used in animations during video recording screens
--nc-live-control-succeed-color	rgb(25, 216, 115)		colour indicating that the real-time control over sharpness is on
--nc-live-control-fail-color	rgb(255, 57, 57)		colour indicating that the real time control on sharpness is not passing

Example of a CSS file

:root {
  --nc-branding-logo-image: url('https://s3-eu-west-1.amazonaws.com/tpd/logos/60db5eecb9d0560001052418/0x0.png');
  --nc-branding-logo-width: 170px;
  --nc-branding-logo-height: 170px;
  --nc-font-family: 'Courgette', serif;
  --nc-font-color: black;
  --nc-font-size: 16px;
  --nc-font-weight: 400;
  --nc-button-active-background: #22819f;
  --nc-button-active-color: #affffa;
  --nc-button-disabled-background: rgba(174, 206, 214, 0.5);
  --nc-button-disabled-color: gray;
  --nc-button-font-size: 16px;
  --nc-button-font-weight: bold;
  --nc-button-border-radius: 40px;
  --nc-button-text-transform: none;
  --nc-checkbox-container-checked-background: transparent;
  --nc-checkbox-background: #22819f;
  --nc-checkbox-checkmark-color: #affffa;
  --nc-checkbox-border-color: #014AD8;
  --nc-checkbox-width: 26px;
  --nc-checkbox-height: 26px;
  --nc-link-color: #014AD8;
  --nc-box-background: #baf7ff;
  --nc-box-border-radius: 20px;
  --nc-box-document-type-background: #baf7ff;
  --nc-box-document-type-border-radius: 40px;
  --nc-progress-bar-background: #56dfb0;
  --nc-validation-color: #1ac6ff;
  --nc-live-control-succeed-color: #1ac6ff;
  --nc-live-control-fail-color: #ff0071;
}
@font-face {
  font-family: 'Courgette';
  font-style: normal;
  font-weight: 400;
  src: url(https://fonts.gstatic.com/s/courgette/v13/wEO_EBrAnc9BLjLQAUk1VvoK.woff2) format('woff2');
  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
}

List of notable CSS classes

There are several CSS classes in the interface that are easily identifiable with a browser developer's tool, We list below the main CSS classes to be used to target each page elements:

Video FaceMatch text customization

To achieve full visual integration, in addition to the appearance, you can also configure the interface texts for video identification, by supplying an additional file named strings.custom-video-identification_[lang].json to be included in the SignBook customisation ZIP archive.

• strings.custom-video-identification_[lang].json: Used to redefine texts for the selected language. Replace [lang] with the corresponding language code (example: fr or en). It is advisable to use a suitable editor (e.g. Notepad++) to edit this file in JSON FORMAT. Note that this file must be encoded in UTF-8.
  • Customisation files available :
    • strings.custom-video-identification_fr.json : Default file
    • strings.custom-video-identification_en.json : English file
    • strings.custom-video-identification_it.json : Italian file
    • strings.custom-video-identification_es.json : Spanish file
    • strings.custom-video-identification_nl.json : Dutch file
    • strings.custom-video-identification_pt.json : Portuguese file
    • strings.custom-video-identification_ro.json : Romanian file
    • strings.custom-video-identification_de.json : German file
    • strings.custom-video-identification_hr.json : Croatian file

It is recommended to redefine only those keys that you feel need to be changed. If you do not wish to modify certain keys, you do not need to provide them, as the default value will automatically be used.