OneSpan Sign How To: Customizing the Signing Ceremony
With OneSpan Sign, you have the ability to customize several aspects of the signing ceremony to fit your application’s needs. This allows you to more seamlessly integrate eSignLive’s signing experience within your application. In this blog, I will show you how to customize the signing ceremony with the Java SDK, .NET SDK, and REST API.
Document Package Level Settings
Before getting into the code, I will give you a brief description of each available package and ceremony layout settings. It is important to note that it is not required to specify any of these settings. They will default to the values shown below if not specified. Document Package Settings [table id=3 /] Ceremony Layout Settings Below is OneSpan Sign’s default signing ceremony layout. Each of the sections is labeled for convenience.
Document Package Settings
| Setting Name | Document Package Settings Method | Description |
|---|---|---|
| In-person | withInPerson | Whether all documents in a package have to be signed on the same device. |
| withoutInPerson (default) | ||
| Opt-Out | withOptOut (default) | Allow a signer not to participate in the signing ceremony. |
| withoutOptOut | ||
| Opt-Out Reason | withOptOutReason | If a signer decides to opt-out, he/she can select a reason for their withdrawal. |
| Language Dropdown | withLanguageDropdown (default) | Whether the language drop down menu from the signing ceremony page is displayed. |
| withoutLanguageDropdown | ||
| Owner in-person dropdown | hideOwnerInPersonDropdown | When in-person is enabled, decide whether the package is owner is present in the signer dropdown. |
| showOwnerInPersonDropdown (default) | ||
| First Affidavit | disableFirstAffidavit | When in-person is enabled, decide whether the first affidavit page is shown when switching signers from the dropdown. |
| enableFirstAffidavit (default) | ||
| Second Affidavit | disableSecondAffidavit | When in-person is enabled, decide whether the second affidavit page is shown when switching signers from the dropdown. |
| enableSecondAffidavit (default) | ||
| Decline | withDecline | Whether a signer can decline the document package. |
| withoutDecline (default) | ||
| Watermark | withWatermark (default) | Whether the signed documents are stamped with the OneSpan Sign logo with each signature. |
| withoutWatermark | ||
| Capture text | withCaptureText | Whether the signed documents are being stamped with the date, time, and signer’s name at each location they were signed. |
| withoutCaptureText (default) | ||
| Hand-over link | withHandOverLinkHref | Replaces the continue button in the signing ceremony. The user will be redirected to a URL you specify. |
| withHandOverLinkText | The text that will appear on the handover button. | |
| withHandOverLinkTooltip | The text that will appear when hovering over the handover button. | |
| Download Button | withDocumentToolbarDOwnloadButton (default) | Whether the download button is available. |
| withoutDocumentToolbarDownloadButton | ||
| Dialog on complete | withoutDialogOnComplete (default) | |
| withDialogOnComplete | Whether the completion dialog, which asks the signers if they want to review the documents or leave the system, is shown after signing. |
Ceremony Layout Settings
Below is OneSpan Sign’s default signing ceremony layout. Each of the sections is labeled for convenience.
| Setting Name | Ceremony Layout Settings Method | Description |
|---|---|---|
| Navigator | withNavigator (default) | Show the navigator. It directs the signer to the next available signature. |
| withoutNavigator | ||
| Global Navigation | withGlobalNavigation (default) | Show the global navigation. |
| withoutGlobalNavigation | ||
| Bread Crumbs | withBreadCrumbs (default) | Show the bread crumbs. |
| withoutBreadCrumbs | ||
| Session Bar | withSessionBar (default) | Show the session bar. |
| withoutSessionBar | ||
| Title | withTitle (default) | Show the title |
| withoutTitle | ||
| Progress Bar | withProgressBar (default) | Show the progress bar. |
| withoutProgressBar | ||
| IFrame | withIFrame | Whether the signing ceremony is embedded in an iFrame. |
| withoutIFrame (default) | ||
| Logo | withLogoSource | Replaces the default OneSpan Sign logo with a custom logo. A valid URL to custom logo needs to be passed as argument. |
| Global Confirm Button | withGlobalConfirmButton (default) | Show confirm button in the global actions area. |
| withoutGlobalConfirmButton | ||
| Download Button | withGlobalDownloadButton (default) | Show the download button in the global actions area. |
| withoutGlobalDownloadButton | ||
| Save As Layout Button | withGlobalSaveAsLayoutButton (default) | Show the “Save As Layout” button in the global actions area. |
| withoutGlobalSaveAsLayoutButton |
The Code
As I mentioned above, I will show you how to customize the signing ceremony with the Java SDK, .NET SDK, and REST API. Go ahead and skip to the section which applies to your method. I will cover the same information in each segment. Full code for this blog can be found in the Developer Community Code Share: Java, .NET, and REST.
OneSpan Developer Community
Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.
Join TodayJava SDK
I will start with the Java SDK. The sample code below shows you how to edit the settings block. If you need a comparison to the basic document object creation or if this is the first time creating a package with the Java SDK, see this previous blog.
.withSettings(DocumentPackageSettingsBuilder.newDocumentPackageSettings()
.withInPerson()
.withOptOut()
.withOptOutReason("Decline terms.")
.withoutLanguageDropDown()
.hideOwnerInPersonDropDown()
.disableFirstAffidavit()
.disableSecondAffidavit()
.withDecline()
.withoutWatermark()
.withCaptureText()
.withHandOverLinkHref("http://www.google.com")
.withHandOverLinkText("Exit to site")
.withHandOverLinkTooltip("You will redirected to Google homepage")
.withDocumentToolbarDownloadButton()
.withDialogOnComplete()
.withCeremonyLayoutSettings(CeremonyLayoutSettingsBuilder.newCeremonyLayoutSettings()
.withNavigator()
.withoutGlobalNavigation()
.withoutBreadCrumbs()
.withSessionBar()
.withTitle()
.withProgressBar()
.withIFrame()
.withGlobalConfirmButton()
.withoutGlobalDownloadButton()
.withoutGlobalSaveAsLayoutButton()
.withLogoSource("http://www.logo-maker.net/images/common/company-logo8.gif")))
.NET SDK
Next, I will cover the .NET SDK. The sample code below shows you how to edit the settings block. If you need a comparison to the basic document object creation or if this is the first time creating a package with the .NET SDK, see this previous blog.
.WithSettings(DocumentPackageSettingsBuilder.NewDocumentPackageSettings()
.WithInPerson()
.WithOptOut()
.WithOptOutReason("Decline terms.")
.WithoutLanguageDropDown()
.HideOwnerInPersonDropDown()
.DisableFirstAffidavit()
.DisableSecondAffidavit()
.WithDecline()
.WithoutWatermark()
.WithCaptureText()
.WithHandOverLinkHref("http://www.google.com")
.WithHandOverLinkText("Exit to site")
.WithHandOverLinkTooltip("You will redirected to Google homepage")
.WithoutDocumentToolbarDownloadButton()
.WithoutDialogOnComplete()
.WithCeremonyLayoutSettings(CeremonyLayoutSettingsBuilder.NewCeremonyLayoutSettings()
.WithNavigator()
.WithoutGlobalNavigation()
.WithoutBreadCrumbs()
.WithSessionBar()
.WithTitle()
.WithProgressBar()
.WithIFrame()
.WithGlobalConfirmButton()
.WithoutGlobalDownloadButton()
.WithoutGlobalSaveAsLayoutButton()
.WithLogoImageSource("http://www.logo-maker.net/images/common/company-logo8.gif")))
REST API
Finally, I will cover the REST API. The sample JSON below shows you how to edit the settings object. I included that will create a new document package with example settings for convenience. If you need a comparison to the basic document object creation or if this is the first time creating a package with the REST API, see this previous blog.
{
"settings": {
"ceremony": {
"events": {
"complete": {
"dialog": true,
"redirect": ""
}
},
"inPerson": true,
"declineButton": true,
"declineReasons": [],
"disableDeclineOther": false,
"disableDownloadForUncompletedPackage": false,
"disableFirstInPersonAffidavit": true,
"disableInPersonAffidavit": false,
"disableOptOutOther": false,
"disableSecondInPersonAffidavit": true,
"documentToolbarOptions": {
"downloadButton": true
},
"handOver": {
"title": "You will be redirected to Google homepage",
"href": "http://www.google.com",
"text": "Exit to site"
},
"hideCaptureText": false,
"hideLanguageDropdown": true,
"hidePackageOwnerInPerson": true,
"hideWatermark": true,
"maxAuthFailsAllowed": 3,
"optOutButton": true,
"optOutReasons": [
"Decline terms."
],
"style": null,
"layout": {
"footer": {},
"iframe": true,
"navigator": true,
"brandingBar": {
"logo": {
"src": "/sites/default/files/blog/images/company-logo8.gif",
"link": ""
}
},
"header": {
"feedback": true,
"globalActions": {
"confirm": true,
"download": false,
"hideEvidenceSummary": false,
"saveAsLayout": false
},
"titleBar": {
"title": true,
"progressBar": true
},
"breadcrumbs": false,
"globalNavigation": false,
"sessionBar": true
}
}
}
},
"type": "PACKAGE",
"status": "DRAFT",
"name": "Customizing Signing Ceremony"
}
Running Your Code
You can now go ahead and run your code. Depending on the settings you chose, your end result might be different from mine. If you followed my example, below is a screenshot of what you might expect:
There you go. You have successfully customized the signing ceremony.
If you have questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the developer community forums:
https://developer.onespan.com. That's it from me. Thank you for reading! If you found this post helpful, please share it on Facebook, Twitter, or LinkedIn.
