Search
  1. Home
  2. Documentation
  3. OneSpan Sign
  4. Guides
  5. Feature Guides
  6. Using JavaScript Event Notifiers

Using JavaScript Event Notifiers

Last modified: 2024-11-01

Event Notifier

To download the full code sample see our Code Share site.

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 OneSpan Sign 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.

Listening for OneSpan Sign events

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

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

For more information on allowing cross-origin communication between your parent window and an iFrame, click here.

Receving Messages

Next, define the receiveMessage function as follows:

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;
      }
}

If you do not configure your system to listen to ESL:MESSAGE:REGISTER and then send back ESL:MESSAGE:ACTIVATE_EVENTS, you will not be able to receive any further events. You must include the following in your receiveMessage function. 

  case 'ESL:MESSAGE:REGISTER':
				event.source.postMessage('ESL:MESSAGE:ACTIVATE_EVENTS', origin);
				break;
				default:
				event.source.postMessage(data, origin)
			break;

This is the minimal code needed to setup an Event Notifier, where the first switch case explicitly tells OneSpan Sign that you want to register for event listening.

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 OneSpan Sign 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 OneSpan Sign of the same event.
     setTimeout(function(){
       event.source.postMessage(data, origin);
     }, 5000);
     break;
   ...
}

For those events that can be interrupted, OneSpan Sign will not resume its normal activity until your parent container posts back the same message defined by the line event.source.postMessage(data, origin).

For more information on which events can be interrupted, see Notification Event Types.

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

Here is the expected order of events for a typical transaction with one external signer, a default Consent Document, and one document to be signed:

ESL:MESSAGE:REGISTER

ESL:MESSAGE:SUCCESS:DOCUMENT_NAVIGATION

ESL:MESSAGE:SUCCESS:DOCUMENT_VIEW

ESL:MESSAGE:STARTED:ACCEPT

ESL:MESSAGE:SUCCESS:ACCEPT

ESL:MESSAGE:STARTED:DOCUMENT_NAVIGATION

ESL:MESSAGE:SUCCESS:DOCUMENT_NAVIGATION

ESL:MESSAGE:SUCCESS:DOCUMENT_VIEW

ESL:MESSAGE:STARTED:DOCUMENT_CONFIRM

ESL:MESSAGE:SUCCESS:DOCUMENT_CONFIRM

ESL:MESSAGE:STARTED:SIGNER_COMPLETE

ESL:MESSAGE:SUCCESS:SIGNER_COMPLETE

ESL:MESSAGE:STARTED:SIGNER_COMPLETE_REVIEWED

ESL:MESSAGE:SUCCESS:SIGNER_COMPLETE_REVIEWED

Was this information helpful?
X