OneSpan Sign Release 11.43: Enhancements in SDKs

OneSpan Sign version 11.43 was recently deployed to the preview environment. In this latest version, we introduced several new methods of authenticating a recipient's identity, continued to improve the New Signer Experience and new sender UI in many aspects, enhanced SDKs to support new features, and more. For a complete list of product updates, check the 11.43 Release Note. Also, refer to our Trust Center and find the deployment dates for all our environments.

In this blog, we will explore another newly introduced Javascript event notifier, and then focus on the recent enhancements in both Java and .NET SDKs. Without further delay, let’s get started!

New Javascript Notifier Event

When a signing link is embedded and presented in an iFrame, the OneSpan Sign Signing Ceremony sends a Javascript event notifier to your parent window to inform the change of status. The event notifications is triggered by particular events of interest and serves different requirements and use cases. For example, when a signer has completed the transaction, your parent window could listen to the “ESL:MESSAGE:SUCCESS:SIGNER_COMPLETE” event and proceed with the signing process accordingly.

Since release 11.43, an additional Javascript notification has been introduced for in-person or notarized transactions when a signer has finished signing their part and is ready to click the “Done” button to return to the signer switch page. 

Your parent window could expect a notification message with signer ID appended, see below table:

Note that this table references the signer ID. For REST developers, it points to the “roles” > “signers” > “id” in your package JSON. For SDK users, it’s either the custom ID for signers or the sender ID for the transaction owner.

New Callback Notification for SDKs

Callback notifications, on the other hand, send notifications to your backend (instead of browser) when a certain event is triggered. In the previous blog, we demonstrated a newly introduced callback event, “Document Viewed”, which triggers when a signer navigates to a document. After version 11.43, developers can now register this event through the SDKs. See the code snippets below:

Java SDK:

final String callback_url = "http://my.url.com";
final String callback_key = "myCallbackKey";
eslClient.getEventNotificationService().register(EventNotificationConfigBuilder.newEventNotificationConfig(callback_url).withKey(callback_key)
				.forEvent(NotificationEvent.DOCUMENT_VIEWED));

.NET SDK:

OssClient ossClient = new OssClient(API_KEY, API_URL);
ossClient.EventNotificationService.Register(EventNotificationConfigBuilder.NewEventNotificationConfig("https://my.address.com")
                    .WithKey("somekeyhere")
                    .ForEvent(NotificationEvent.DOCUMENT_VIEWED)
                    .build());

Note that in order to leverage this feature, you need to upgrade your SDK to version 11.43 or later. 

Retrieve Sub-account API keys 

The Sub-account feature enables an organization to create child (or even grandchild) accounts within the organization's master account on the basis of its departments, geographical locations, or lines of business. A sub-account could have its own brandings and account settings independent of other subaccounts or the master account.

Similar to the integrations on the master account, implementing use cases on sub-accounts depends on retrieving the sub-account admin’s API Key first. Considering the fact that a signer could be associated with multiple sub-accounts, if the person has been assigned a role in each sub-account, this generates multiple distinct API Keys for each sub-account, which can be difficult to retrieve and manage. 

To mitigate this pain point, OneSpan Sign has exposed an API exclusively to retrieve the sub-account API Keys of a signer where the person has API access. See below:

HTTP Request

GET /api/account/subaccountApiKeys

HTTP Headers

Authorization: Basic api_key / Bearer access_token
Accept: application/json

Example Response:

[
    {
        "accountUid": "vMAyraE2jrc7",
        "accountName": "subaccount1",
        "apiKey": "N1R6RxxxxBVw=="
    },
    {
        "accountUid": "jBOspAfonpE2",
        "accountName": "subaccount2",
        "apiKey": "N1R6RxxxxrVw=="
    }
]

Note:

• As the authorization API Key, the signer must be assigned a role in that particular sub-account with “User Management”, “Sub Account Management”, and “API Access” permissions. This is typically the “Admin” role or a customized role with similar permissions.
• The API returns a list of sub-accounts where the signer has API access. Apparently, it includes the authorization API Key. To be more specific, having API access means the signer needs to be assigned a role with “API Access” permission in those sub-accounts.

Since release 11.43, the same functionality is supported by SDK as well.

Java SDK:

EslClient eslClient = new EslClient(API_KEY, API_URL);	
List<SubAccountApiKey> subAccountApiKeys = eslClient.getAccountService().getSubAccountApiKeys();

.NET SDK:

OssClient ossClient = new OssClient(apiKey, apiUrl);
IList<SubAccountApiKey> subAccountApiKeys = ossClient.AccountService.getSubAccountApiKey();

Conclusion

There it is. In this blog, we showcased the newly introduced Javascript Notifier event and walked you through the recent SDK updates and enhancements. 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!