OneSpan Sign Release 11.42: Revamped Javascript Notifications

OneSpan Sign version 11.42 was recently deployed to the preview and sandbox environment. In this latest version, we added new JavaScript and Callback events, delivered new features to Virtual Room signing, added support for more New Signer Experience UI components to format in markdown, and more. For a complete list of product updates, check the 11.42 Release Note. Also refer to our Trust Center and find the deployment dates for all our environments.

In this blog, we will first have a quick review of the mechanism behind the Javascript event notifier. Then, we will explore the newly introduced events, so that you’ll have a better idea how these changes can facilitate your integration. Without further delay, let’s get started!

Quick Review of Javascript Notifier

When the Signing Ceremony is embedded in an iFrame or a WebView, the Event Notifier sends notifications to your parent window when specific actions are triggered. This provides information about the signing progress and comes in handy if you want to control the signing flow when a certain step has been accomplished. For example, to redirect a signer to a different web page once they have completed signing.

To set up an Event Notifier, follow the steps below:

Step 1: Listen to OneSpan Sign’s message events, as shown below:

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

Step 2: Handle the received event as needed. An example could be:

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 the message “ESL:MESSAGE:ACTIVATE_EVENTS” in order to receive further events.

Above code examples are used for desktop experience. If you are developing with native mobile Apps, refer to our previous blog “WebView Support in Android Devices” for more detailed instructions.

Newly Introduced Event Types

When a signer performs actions during the signing, for example when the signer has declined to sign, the Signing Ceremony window sends particular message to your parent window. You will find a list of available event types that your event notifier can listen for in the Using JavaScript Event Notifiers guide.

On top of what have been listed there, there are three event types supported since version 11.42:

Document View Event

Essentially the document view event “ESL:MESSAGE:SUCCESS:DOCUMENT_VIEW:<document Id>“ triggers at the same time as the document navigation event “ESL:MESSAGE:SUCCESS:DOCUMENT_NAVIGATION”. However, it also provides additional information about the document ID, so your integration knows which exact document the signer is currently viewing.

Working in tandem with Document Accept “ESL:MESSAGE:SUCCESS:DOCUMENT_ACCEPT” and Document Confirm “ESL:MESSAGE:SUCCESS:DOCUMENT_CONFIRM” events, your front end code is able to track the signing status in real time without relying on the callback notifications.

Signer Complete Reviewed Event

The Signer Complete Event gets triggered as long as a signer has signed all the required documents. However this is not enough if your business wants to make sure the signer has also walked through all the review-only documents. Signer Complete Reviewed Event is designed to mitigate this pain point by its very nature, and it only sends a notification when the signer has navigated to the last document and clicked the “FINISH” button.  

Leveraging this event is useful when the last document of your transaction is a review-only document, but you don’t want to get notified until the signer has browsed through all the content. Instead of monitoring the Signer Complete Event, Signer Complete Reviewed Event is a perfect replacement for this scenario. Check the video below:

Another typical use case is when the signer is a reviewer. In previous versions, your application would not have been notified whether the signer completed reviewing, because there’s simply no pending signatures. After this event gets introduced, your integration gets control over the workflow as long as the reviewer clicked the “FINISH” button. Watch the video below for more information:

There it is. In this blog, we’ve walked through the basics of Javascript Notifier and demonstrated the usages of the newly introduced events. If you have any questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the Developer Community Forums. Your feedback matters to us!