JavaScript Event Notifiers

When the Signer Experience is embedded in an iFrame, the Event Notifier sends notifications to your parent window when specific actions are triggered. Using these notifications you can interrupt the typical ValidSign workflow using your own customized logic, and then resume normal activities after. This is useful if you want to something to happen after certain steps of the Signer Experience have been accomplished, such as redirecting a signer to a different web page once they have completed signing.

Event Notifiers

Event Notifiers

Listening for ValidSign events

To create an Event Notifier your application must be listening for ValidSign message events. To set this up, use this command, using plain JavaScript

window.addEventListener('message', receiveMessage, false);

Receving Messages

Next, define the receiveMessage function as described below:

function receiveMessage(event) {
      var origin = event.origin || event.originalEvent.origin;
      var data = event.data;
      console.log(data, origin);
 
      switch (data) {
            case 'ESL:MESSAGE:REGISTER':
                  event.source.postMessage('ESL:MESSAGE:ACTIVATE_EVENTS', origin);
                  break;
            default:
                  event.source.postMessage(data, origin)
                  break;
      }
}

Results

A common use of an Event Notifier can be to redirect a signer to a different page once they have completed signing. Here is an example of how that would be done:

case 'ESL:MESSAGE:SUCCESS:SIGNER_COMPLETE ':
	event.source.postMessage(data, origin);
	window.location.href = "https://www.example.com"; //redirect page
	break;

Interrupting ValidSign Activity

Using an Event Notifier, some events can be temporarily stopped. Here is some sample code that shows you how to do that:

switch (data) {
   ...
   case 'ESL:MESSAGE:STARTED:DOCUMENT_NAVIGATION':
     // Do some customized tasks, then notify ValidSign of the same event.
     setTimeout(function(){
       event.source.postMessage(data, origin);
     }, 5000);
     break;
   ...
}

Notification Event Types

The following table describes the types of notification events your Event Notifier can listen for.

Event Name	Description	Can Event Be Temporarily Stopped?
ESL:MESSAGE:STARTED:DOCUMENT_ACCEPT	A signer has started to accept a consent or disclosure.	No
ESL:MESSAGE:SUCCESS:DOCUMENT_ACCEPT	A signer has successfully accepted a consent or disclosure.	Yes
ESL:MESSAGE:ERROR:DOCUMENT_ACCEPT	A signer has failed in their attempt to accept a consent or disclosure.	No
ESL:MESSAGE:STARTED:PACKAGE_OPT_OUT	A signer has started to opt out of a transaction.	No
ESL:MESSAGE:SUCCESS:PACKAGE_OPT_OUT	A signer has successfully opted out of a transaction.	Yes
ESL:MESSAGE:ERROR:PACKAGE_OPT_OUT	A signer has failed in their attempt to opt out of a transaction.	No
ESL:MESSAGE:STARTED:PACKAGE_DECLINE	A signer has started to decline a transaction.	No
ESL:MESSAGE:SUCCESS:PACKAGE_DECLINE	A signer has successfully declined a transaction.	Yes
ESL:MESSAGE:ERROR:PACKAGE_DECLINE	A signer has failed in their attempt to decline a transaction.	No
ESL:MESSAGE:SUCCESS:DOCUMENT_VIEW:<document Id>	A signer has viewed a document.	No
ESL:MESSAGE:STARTED:DOCUMENT_CONFIRM	A signer has started to confirm a document.	No
ESL:MESSAGE:SUCCESS:DOCUMENT_CONFIRM	A signer has successfully confirmed a document.	Yes
ESL:MESSAGE:ERROR:DOCUMENT_CONFIRM	A signer has failed in their attempt to confirm a document.	No
ESL:MESSAGE:STARTED:SIGNER_COMPLETE	A signer has started to complete a transaction.	Yes
ESL:MESSAGE:SUCCESS:SIGNER_COMPLETE	A signer has successfully completed a transaction.	No
ESL:MESSAGE:STARTED:SIGNER_COMPLETE_REVIEWED	A signer has started reviewing documents.	Yes
ESL:MESSAGE:SUCCESS:SIGNER_COMPLETE_REVIEWED	A signer has completed reviewing documents.	No
ESL:MESSAGE:STARTED:DOCUMENT_NAVIGATION	The user has started navigating to another document.	Yes
ESL:MESSAGE:SUCCESS:DOCUMENT_NAVIGATION	The user has successfully navigated to another document.	No