OneSpan Sign Release 11.41: Auto-Redirect Handover URL

OneSpan Sign version 11.41 was recently deployed to the preview and sandbox environment. In this latest version, we introduced several enhancements involving handover URL. We also delivered the in-app reporting feature that allows account administrators to download structured data of monthly transactions. On top of that, we’ve continuously improved the New Signer Experience like to support JavaScript notifications in Web Views, and more. For a complete list of product updates, check the 11.41 Release Note. Also refer to our Trust Center and find the deployment dates for all our environments.

In this blog, we will showcase you three improvements and product behavior changes around handover URL, so that you will have a better idea how to leverage this feature in your integration. Without further delay, let’s get started!

Auto-Redirect Signers After Signing

A Handover URL is a redirect link that allows you to determine where the signing ceremony will be relocated after a recipient interacts with a transaction. You could simply redirect the link to your organization’s home page or utilize this redirection mechanism as a webhook and forward the page back to your business flow. This latter option is especially appealing if you are not embedding the signing ceremony into an iFrame but still need to control the signing flow.

In the previous signing experience, a thank you summary page would be displayed after signing, and the signer had to manually click on the next step button to trigger the redirection. Although you could definitely include descriptive instructions in the page, it’s still possible that some signers ignored to tap the button and became uncertain what to do next.

This will no longer be the case since version 11.41, because the account owners have the option to redirect signers after they finished signing. Instead of the thank you summary page, an interim page will be displayed during the redirection to inform signers of what is happening.

For now, signers will remain on this interim page for a hard-coded 10 seconds before being redirected, meanwhile they can manually trigger the redirection at any time.

Note:

• Returning to the signing ceremony after completion will display the summary page instead of triggering the auto-redirection.
• The title and the body of this page can be customized. Simply provide your own copy to our Support Team, and our support agents will help you set up your account. 

We will showcase how to enable this feature at the end of this blog.

Configurable Handover URL Parameters

Once redirected, OneSpan Sign appends extra URL parameters to the handover URL, so that your application can be aware of the event and handle it accordingly.

For example, if you specified the Handover URL as "https://localhost/oss/handover" after the recipient with signer ID of “Signer1” has declined the transaction (ID of “T840KlFsIeC--LqGu9O9Enp9T6I”), information associated with this event will be passed by parameters, and the actual link the recipient will hit looks like:

https://localhost/oss/handover?package=T840KlFsIeC--LqGu9O9Enp9T6I%3D&signer=Signer1&status=PACKAGE_DECLINE

These three parameters each represent:

• Package: This refers to the transaction ID
• Signer: This refers to the signer ID rather than the role ID. For further reading about the detailed differences between the signer and role, read our previous blog “Role vs Signer – Part 1”.
• Status: The available values are “SIGNER_COMPLETE” or “PACKAGE_DECLINE”.

In this 11.41 release, OneSpan Sign introduced the ability to have package senders choose whether to display part of these three parameters depending on your unique requirement and to better protect signer’s privacy. By default, the handover URL will still be attached to all of the three parameters, and we will showcase how to define partial parameters in below section.

An Important Notice

In terms of Handover URL, there are known inconsistencies between the New Signer Experience, Classic Signing Experience, and Mobile Signing Ceremony. Due to the fact that Classic Signing Experience is about to be deprecated in SaaS environments, it is important to understand these inconsistencies and make plans to update your existing integrations:

In the Classic Experience, the “status” parameter had three potential values “COMPLETED”, “PACKAGE_OPT_OUT” and “PACKAGE_DECLINE”. These have been changed to “SIGNER_COMPLETE” and “PACKAGE_DECLINE” in New Signer Experience.

Additionally, “COMPLETED” has been renamed to “SIGNER_COMPLETE”. If your integration makes use of the “status” parameter, you’d update your integration to replace the parameter value or to accept both statuses to avoid conflicts. Below pseudo code shows you the idea:

Existing Code: status.equals(“COMPLETED”)
New Code: status.equals(“COMPLETED”) OR status.equals(“SIGNER_COMPLETE”)

Because the opt out feature is not supported in New Signer Experience, the value “PACKAGE_OPT_OUT” will no longer be available.

How to Enable Auto-Redirect and Configure Parameters

RESTful API

Enabling auto-redirect and configuring URL parameters are both defined in the package setting “settings” > “ceremony” > “handOver”. The example below demonstrates how to organize the “handOver” node: 

{
  "status": "DRAFT",
  "settings": {
    "ceremony": {
      "handOver": {
        "href": "https://www.google.com",
        "text": "Next Step",
        "title": "Next Step",
        "autoRedirect": true,
        "parameters": ["PACKAGE", "SIGNER", "STATUS"]
      }
    }
  },
  "type": "PACKAGE",
  "name": "Customizing Signing Ceremony"
}

Note:

• By default, “autoRedirect” will be set to false.
• Although the Values of “parameters” is case insensitive, the actual parameter name will be all lower cases
• To remove all handover URL parameters, simply leave an empty array ("parameters":[]).

The sample code below demonstrates the equivalent SDK code to build a DocumentPackage object with auto-redirection and configuration parameters. Before following the code, make sure you’ve upgraded your SDK to version 11.41 or later.

Java SDK

DocumentPackage package = PackageBuilder.newPackageNamed("Test Handover URL - " + System.currentTimeMillis())
		……
		.withSettings(DocumentPackageSettingsBuilder.newDocumentPackageSettings()
				.withHandOverLinkHref("https://www.google.com")
				.withHandOverLinkText("Next Step")
				.withHandOverLinkTooltip("Next Step")
				.withHandOverLinkAutoRedirect()
				.withHandOverLinkParameters(new HashSet<String>(Arrays.asList("signer", "package", "status")))
				)
		.build();

.NET SDK

DocumentPackage package = PackageBuilder.NewPackageNamed("Test Handover URL - " + System.currentTimeMillis())
		……
		.WithSettings(DocumentPackageSettingsBuilder.NewDocumentPackageSettings()
				.WithHandOverLinkHref("https://www.google.com")
				.WithHandOverLinkText("Next Step")
				.WithHandOverLinkTooltip("Next Step")
				.WithHandOverLinkAutoRedirect()
				.WithHandOverLinkParameters(new HashSet<String>("signer", "package", "status"))
				)
		.Build();

Account Level

You can either specify these settings on a transaction basis or set the default value at the account level by contacting our Support Team. If you choose the latter case, all newly created transactions will inherit these settings.

There it is. In this blog, we have covered recent enhancements regarding Handover URL. Stay tuned, and we will bring you more release updates in future installments.

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!

OneSpan Developer Community

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

Join Today