What’s new in the DocuSign Android SDK
The DocuSign Android SDK is engineered for signing reliability and seamless integration. Developers are now able to integrate with the most robust signing solution within mobile apps regardless of internet connectivity. You may already know that the DocuSign Android SDK offers the ability to sign when in poor connectivity situations. But now the SDK also supports the myriad of signing features available with embedded signing (online signing). Additionally, with v1.7.6, we've included changes to better tailor the integration of SDK components within your app. Let's walk through some of these new additions.
SDK components
DocuSign SDK is categorized into components so that you can include the relevant component based on your requirement. This componentization saves disk space when the SDK component is included in your app compared to including the complete SDK. DocuSign SDK comprises the following components:
Offline Signing
To use SDK’s offline signing feature, include the following SDK components in your app’s build.gradle:
dependencies {
implementation 'com.docusign:androidsdk:1.7.6'
implementation 'com.docusign:sdk-common:1.7.6'
implementation 'com.docusign:sdk-offline-signing:1.7.6'
}
Online Signing
To use SDK’s online signing feature, include the following SDK components in your app’s build.gradle:
dependencies {
implementation 'com.docusign:androidsdk:1.7.6'
implementation 'com.docusign:sdk-common:1.7.6'
}
eSignature API
eSignature API includes the broader set of DocuSign API functions. In addition to the API methods provided by the SDK, this component also provides a way to access the eSignature API directly from the SDK itself. To use eSignature API, include the following SDK components in your app’s build.gradle:
dependencies {
implementation 'com.docusign:androidsdk:1.7.6'
implementation 'com.docusign:sdk-common:1.7.6'
implementation 'com.docusign:sdk-esign-api:1.7.6'
}
Captive Signing
Users who don’t have DocuSign accounts can still sign documents with our Captive Signing feature. A Captive Signing Recipient is a recipient who does not have a DocuSign account. The Android SDK provides an API to launch an embedded signing session for a Captive Signing recipient. Once the signing session is launched, the recipient can preview, print, and download the document. Captive Signing also allows you to apply branding settings, which can be controlled from the DocuSign web portal to control the display of menu options during Captive Signing. Check out the TGK sample App for usage of Captive Signing. To see Captive Signing in action, watch this demo of Captive Signing from the TGK sample app:
The app needs to generate the signing URL and invoke the following Captive Signing API:
val signingDelegate = DocuSign.getInstance().getSigningDelegate()
signingDelegate.launchCaptiveSigning(
context,
signingURL,
null,
null,
object : DSCaptiveSigningListener {
override fun onStart(envelopeId: String) {
}
override fun onRecipientSigningSuccess(envelopeId: String, recipientId: String) {
}
override fun onRecipientSigningError(envelopeId: String, recipientId: String, exception: DSSigningException) {
}
override fun onSuccess(envelopeId: String) {
}
override fun onCancel(envelopeId: String, recipientId: String) {
}
override fun onError(envelopeId: String?, exception: DSSigningException) {
}
})
Anchor Tabs
If the envelope document contains a lot of tags, then it will be cumbersome to specify x and y positions for all the tags manually. In that case, you can use our Anchor tabs feature in the Android SDK. You just need to specify an anchor string in the SDK’s envelope creation API call, and the tags will be placed automatically based on the anchor string. While creating the envelope using our SDK API, for each anchor string, you can create a new tab; and if the document contains multiple instances of that anchor string, then the tabs for all those will be created automatically. To use anchor tags, invoke the DSTab.Builder() method:
val tabBuilder = DSTab.Builder()
.documentId("1")
.recipientId("1")
.pageNumber(1)
.anchorString("Signature") // Auto places signature tags in the document based on the specified anchor string.
.anchorXOffset(10)
.anchorYOffset(10)
.anchorCaseSensitive(false)
.type(DSTabType.SIGNATURE)
.build()
Online Signing
As of v1.7.6, the DocuSign Android SDK provides an API method for coordinating signing with an embedded web view, otherwise known as Online Signing. With Online Signing, developers can use a familiar but enhanced signing view similar to the ones found through browsers, but customized for mobile usage.
Online Signing is compatible with templates and envelopes created from the SDK API. Using Online Signing through the SDK enables developers to reduce complexity and potential points of failure that can be introduced with multiple moving parts between the REST API and browsers.
For example, consider a hypothetical financial services scenario: TGK Capital would like to provide their investors a seamless signing experience to sign investor agreement contracts. TGK Portfolio Manager uses the TGK Capital app, which is integrated with the DocuSign Android SDK for signing agreements with their investors.
Our Online Signing demo shows a preview of the TGK Capital sample app, which uses the DocuSign Android SDK Online Signing feature:
Let’s take a look at how this works with templates.
Online Signing using templates
Say you have a repeatable workflow and need to use a form over and over again. Now, you can repeat your workflow using a template by invoking the following SDK API method. To use the existing template, simply call the following methods:
val templateDelegate = DocuSign.getInstance().getTemplateDelegate()
templateDelegate.useTemplateOnline(context,
templateId,
envelopeDefaults,
object : DSOnlineUseTemplateListener {
override fun onStart(envelopeId: String) { }
override fun onCancel(envelopeId: String,
recipientId: String) { }
override fun onComplete(envelopeId: String,
onlySent: Boolean) { }
override fun onError(envelopeId: String?,
exception: DSTemplateException) { }
override fun onRecipientSigningError(envelopeId: String,
recipientId: String,
exception: DSTemplateException) { }
override fun onRecipientSigningSuccess(envelopeId: String,
recipientId: String) { }
})
You can also provide envelopeDefaults in the above API call to prefill the template with recipient details, tags values, custom fields, and envelope details.
Online Signing using an envelope created from the SDK
Invoke the following SDK API method to perform Online Signing using an envelope which is created from scratch from your own PDF. You’ll create an an envelope and then launch the signing views as follows:
val envelopeDelegate = DocuSign.getInstance().getEnvelopeDelegate()
// Create envelope
envelopeDelegate.composeAndSendEnvelope(envelope,
object : DSComposeAndSendEnvelopeListener {
override fun onSuccess(envelopeId: String,
isEnvelopeSent: Boolean) {
val signingDelegate=
DocuSign.getInstance().getSigningDelegate()
// Launch Online Signing using envelope that is created from scratch
signingDelegate.createEnvelopeAndLaunchOnlineSigning(
context,
envelopeId,
object : DSOnlineSigningListener {
override fun onStart(envelopeId: String) { }
override fun onSuccess(envelopeId: String) { }
override fun onCancel(envelopeId:String,
recipientId: String) { }
override fun onError(envelopeId: String?,
exception: DSSigningException) { }
override fun onRecipientSigningError(
envelopeId: String,
recipientId: String,
exception: DSSigningException) { }
override fun onRecipientSigningSuccess(
envelopeId: String,
recipientId: String) { }
})
}
override fun onError(exception: DSEnvelopeException) { }
})
Online Signing using an envelope ID from DocuSign
Have an existing envelope that you’ve created or received? All you need is the envelope ID from your existing envelope. You’ll want to invoke the following SDK API method to perform Online Signing:
val signingDelegate = DocuSign.getInstance().getSigningDelegate()
// Launch Online Signing using envelopeId retrieved from DocuSign server/portal
signingDelegate.signOnline(
context,
serverEnvelopeId,
object : DSOnlineSigningListener {
override fun onStart(envelopeId: String) { }
override fun onSuccess(envelopeId: String) { }
override fun onCancel(envelopeId: String,
recipientId: String) { }
override fun onError(envelopeId: String?,
exception: DSSigningException) { }
override fun onRecipientSigningError(envelopeId: String,
recipientId: String,
exception: DSSigningException) { }
override fun onRecipientSigningSuccess(envelopeId: String,
recipientId: String) { }
})
Branding and UI configurations
For a seamless experience, the DocuSign Android SDK now provides API methods to customize the UI of the signing experience to match your app's branding/styling/theme.
What kind of customizations are available to match your app's user experience? Here's the list you can set:
- Action Bar color
- Status Bar color
- Action Bar logo
- Action Bar title text color
- Bottom Toolbar button color
- Bottom Toolbar button text color
- Bottom Toolbar DocuSign image visibility
val appearanceDelegate = DocuSign.getInstance().getAppearanceDelegate()
val appearance = DSAppearance.Builder()
.setActionBarColor(actionBarColor: ColorDrawable)
.setStatusBarColor(statusBarColor: ColorDrawable)
.setActionBarLogo(actionBarLogo: Drawable)
.setActionBarTitleTextColor(actionBarTitleTextColor: ColorDrawable)
.setBottomToolbarButtonColor(bottomToolbarColor: ColorDrawable)
.setBottomToolbarButtonTextColor(bottomToolbarButtonColor: ColorDrawable)
.setBottomToolbarDocuSignImageVisibility(bottomToolbarDocuSignImageVisibility: Boolean)
.build()
appearanceDelegate.appearance = appearance
Sample apps
We’ve also built some useful sample applications to help you get started. The Kotlin sample application for the Android SDK showcases the usage of DocuSign Android SDK APIs and helps ease the integration process by providing you a reference implementation.
The sample app will cover the the following actions that you may require while integrating in your own app:
Login
In the app, you can log in to DocuSign using the SDK's login API method by providing details such as IntegratorKey, ClientSecret and RedirectURI.
Template flow
The app showcases DocuSign signing based on DocuSign templates with some predefined sample templates.
Online Signing
The app shows the usage of the DocuSign Android SDK API for Online Signing with Templates. The sample performs Online Signing using a template when there is a network connection. You can also provide envelopeDefaults in this API if you want to prefill the template with recipient details, template tabs, custom fields, and more.
The app also demonstrates the usage of DocuSign Android SDK API methods for Online Signing by creating the envelope from just a PDF. The app creates the envelope using SDK API methods by providing the documents, recipient details, envelope details, and custom fields. It then performs Online Signing from the created envelope when there is network connection.
Offline Signing
To perform Offline Signing using templates, you must cache the template first. The TGK sample app uses SDK API methods to retrieve templates, cache a template, remove the template, and perform Offline Signing with templates. The sample app performs Offline Signing using a template when there is no network connection. You can also provide envelopeDefaults in this API if you want to prefill the template with recipient details, template tabs, custom fields, and more. Once the document is signed offline in the sample app, you can sync the document when there is a network connection.
The app also shows the usage of DocuSign Android SDK API methods for Offline Signing by creating the envelope from scratch using a PDF file. It creates the envelope using SDK API methods by providing the documents, recipient details, envelope details, and custom fields. The app then performs Offline Signing when there is no network connection.
Envelope flow
The app showcases document signing based from the envelope created from scratch with a PDF via the SDK.
API additions
More features are categorized below:
Custom Settings
Some coordination screens used for hosted signing may not be necessary within your experience. The DSCustomSettings.Builder() SDK API method will hide the template recipients screen displayed during the signing ceremony using templates. This API is effective only if envelopeDefaults are provided in signing APIs.
val customSettings = DSCustomSettings.Builder()
.setDisplayTemplateRecipientsScreen(false)
.build()
DocuSign.getInstance().getCustomSettingsDelegate().customSettings = customSettings
Retrieving an envelope
The following SDK API method retrieves the actual envelope from DocuSign.
DocuSign.getInstance().getEnvelopeDelegate().getEnvelope(serverEnvelopeId, object : DSGetEnvelopeListener {
override fun onSuccess(envelope: DSEnvelope) { }
override fun onError(exception: DSEnvelopeException) { }
})
Download signing completed document
The following SDK API method retrieves the document that was signed successfully.
val envelopeDelegate = DocuSign.getInstance().getEnvelopeDelegate()
envelopeDelegate.downloadCompletedEnvelopeDocument(envelopeId, object: DSDownloadCompletedEnvelopeListener {
override fun onSuccess(envelopeId: String, fileUri: String) { }
override fun onError(exception: DSEnvelopeException) { }
})
Clear delegates
The following SDK API method clears all SDK delegates and releases the memory.
DocuSign.getInstance().clearDelegates()
