Free trial

Setting Up OneSpan Sign's Event Notifier

eSignature developers
Haris Haidary,
Thumbnail

This blog will walk you through the Event Notifier that was introduced in the 10.13.14 and 11.0.5 releases of OneSpan Sign. When embedding OneSpan Sign’s signing ceremony into an iframe, the Event Notifier can send notifications to the parent host application. This is particularly useful if you want to take actions when certain steps of the signing ceremony have been accomplished. After receiving such a notification, you can interrupt OneSpan Sign’s normal flow to perform some asynchronous task (e.g. ask the user to confirm a request), and then notify OneSpan Sign to resume its normal flow.

Starting the Event Notifier

You can write your OneSpan Sign Event Notifier in plain JavaScript. Your application must be listening to OneSpan Sign’s message events, as shown below:

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

To get your Event Notifier started, your listener should be something along these lines:

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

Upon loading a page in an iframe, OneSpan Sign will initially fire an ESL:MESSAGE:REGISTER event. In return, your application must send back to OneSpan Sign the event ESL:MESSAGE:ACTIVATE_EVENTS. If this doesn’t happen, OneSpan Sign will assume that no one is listening, and no other events will be fired.

Interrupting OneSpan Sign’s Normal Flow of Activity

Some events can be temporarily stopped (the events in question are identified in the third column of the table below). For example, you can change the listener above as follows:

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

	case 'ESL:MESSAGE:SUCCESS:SIGNER_COMPLETE':
		event.source.postMessage('ESL:MESSAGE:SUCCESS:SIGNER_COMPLETE', origin);
		//$("#myIframe").hide();    hide iframe
		window.location.href = "https://www.google.com"; //redirect to google
		break;

	default:
		event.source.postMessage(data, origin)
		break;
}

In the code above, the signer will be redirected to Google's homepage in the parent window (i.e. not inside the iframe) once he/she has completed signing the documents. Note: If events are not sent back as they are received, OneSpan Sign will not resume its normal activity.

Notification Event Types

The following table describes the types of notification events your event listener can listen to.

Event Name Description Can Event Be Temporarily Stopped? Compatible with the Standard Signing Ceremony? Compatible with the Mobile Signing Ceremony?
ESL:MESSAGE:STARTED:DOCUMENT_ACCEPT A signer has started to accept a consent or disclosure. No Yes Yes
ESL:MESSAGE:SUCCESS:DOCUMENT_ACCEPT A signer has successfully accepted a consent or disclosure. Yes Yes Yes
ESL:MESSAGE:ERROR:DOCUMENT_ACCEPT A signer has failed in their attempt to accept a consent or disclosure. No Yes Yes
ESL:MESSAGE:STARTED:PACKAGE_OPT_OUT A signer has started to opt out of a transaction. No Yes Yes
ESL:MESSAGE:SUCCESS:PACKAGE_OPT_OUT A signer has successfully opted out of a transaction. Yes Yes Yes
ESL:MESSAGE:ERROR:PACKAGE_OPT_OUT A signer has failed in their attempt to opt out of a transaction. No Yes Yes
ESL:MESSAGE:STARTED:PACKAGE_DECLINE A signer has started to decline a transaction. No Yes No
ESL:MESSAGE:SUCCESS:PACKAGE_DECLINE A signer has successfully declined a transaction. Yes Yes No
ESL:MESSAGE:ERROR:PACKAGE_DECLINE A signer has failed in their attempt to decline a transaction. No Yes No
ESL:MESSAGE:STARTED:DOCUMENT_CONFIRM A signer has started to confirm a document. No Yes Yes
ESL:MESSAGE:SUCCESS:DOCUMENT_CONFIRM A signer has successfully confirmed a document. Yes Yes Yes
ESL:MESSAGE:ERROR:DOCUMENT_CONFIRM A signer has failed in their attempt to confirm a document. No Yes Yes
ESL:MESSAGE:STARTED:SIGNER_COMPLETE A signer has started to complete a transaction. Yes Yes Yes
ESL:MESSAGE:SUCCESS:SIGNER_COMPLETE A signer has successfully completed a transaction. No Yes Yes
ESL:MESSAGE:STARTED:DOCUMENT_NAVIGATION The user has started navigating to another document. Yes Yes Yes
ESL:MESSAGE:SUCCESS:DOCUMENT_NAVIGATION The user has successfully navigated to another document. No Yes Yes

You can download a complete working example code from the Developer Community Code Share.

If you have questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the developer community forums: developer.esignlive.com. That's it from me. Thank you for reading! If you found this post helpful, please share it on Facebook, Twitter, or LinkedIn.

Haris Haidary
Junior Technical Evangelist
LinkedIn | Twitter 

OneSpan Developer Community

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today

 

Haris Haidary
Go To Top
Share