DocuSign Android SDK: FAQ
Here are some of the most frequently asked questions about the DocuSign Android SDK. For more information, see the Android SDK README or Developer Support.
- Why am I getting an “Invalid access token” error?
When you generate an access token with your JSON Web Token (JWT), the access token has a lifetime of one hour. If you invoke any of the SDK methods used for signing after the token expires, the SDK returns the “Invalid access token” exception.
When using the login() method, make sure that you pass the token value for the expiresIn attribute. After the new access token is generated via the JSON Web Token (JWT Grant) flow, the token expiry value should be passed in the SDK’s login() method.
To be safe, use the SDK's authenticationDelegate.isSessionActive() method to test if the access token is expired or valid. If the token expires, fetch a new access token from your back end and invoke the SDK's login() method with new accessToken and expiresIn values.
- How can I hide or bypass the host signing screen at the beginning of the signing session?
If your app does not need to display the recipients and signing order before hosting, then invoke the following SDK method to hide the host signing screen. This method is only effective if envelope defaults are provided in the signing methods.
val customSettings = DSCustomSettings.Builder() .setDisplayTemplateRecipientsScreen(false) .build() DocuSign.getInstance().getCustomSettingsDelegate().customSettings = customSettings - We don’t want our users sharing the organization’s DocuSign credentials to use the integration. What are our authentication options?
To avoid implicit login or authentication, use an access token for login instead:
// accessToken - Access token that authenticates the user // refreshToken - If the access token can be refreshed, the refresh token. Optional // expiresIn - The number of seconds from the time the access token was provisioned to when it will expire DSAuthenticationDelegate docusignAuthDelegate = DocuSign.getInstance().getAuthenticationDelegate(); docusignAuthDelegate.login(accessToken, refreshToken, expiresIn, context, new DSAuthenticationListener() { @Override public void onSuccess(@NonNull DSUser user) { } @Override public void onError(@NonNull DSAuthenticationException exception) { } });Obtain the access token using one the following:
The JWT Grant authentication flow requires server support. Once the server authenticates and successfully fetches the access token, pass that access token and the expiration time to your app, which in turn will invoke the login() method referenced above.
- Why am I getting a “File not found at specified URI” error while building an envelope using DSEnvelope.Builder?
While creating the envelope using the Android SDK’s DSEnvelope.Builder class, make sure to convert the file to a URI as mentioned below.
File file = new File(Environment.getExternalStorageDirectory(), <filePath>); URI fileURI = file.toURI();When using the DSEnvelope.Builder class, you can set the URI of the document as follows:
.uri(fileURI.toString()); -
How much free space does my device need to cache a template using the Android SDK?
The device needs to have at least roughly 1GB free space to cache a template, depending on document size and the number of fields.
- Can I programmatically configure read-only tabs to a template with the Android SDK?
You can only set the Read Only property for the tab in a template from the DocuSign web portal. From the web, when you place the tab on the document, you will find the tab’s properties on the right side of the UI. There you can select the Read Only property for that tab.
If you prefill tab labels and values when converting the template to an envelope, these fields become read-only during signing. In the DSEnvelopeDefaults class’s tabValueDefaults parameter, you can provide the tab label and the value.
- Why did my envelope fail to sync to my sandbox after signing offline?
Check which environment your app is pointing to.
- If you point your app to the demo environment, you can check the signed/completed envelope at https://www.demo.docusign.net.
- If you point the app to the production environment, you can check the signed/completed envelope at https://www.docusign.net.
- Why did my security questions fail to show up before the signing session?
Security questions are only compatible with online signing (embedded web signing) with DocuSign Android SDK before launching the signing session.
Also, you’ll want to double-check your envelope settings. When sending an envelope from the DocuSign web portal, review the envelope setting In Person ID Check Question.
- Why is the UseTemplateOnline method returning the “No template found” error?
This error indicates that the referenced template is not available. You need to cache the template before invoking the UseTemplateOnline method. You can cache the template using the cacheTemplate method.
- Is there any complete code example that shows how to implement document signing using an embedded signing ceremony and DSEnvelopeDefaults?
The Android SDK Kotlin sample app is comprehensive and showcases the offline and online signing session using DSEnvelopeDefaults.
- 11. Is there a SDK version that does not depend on AndroidX?
The Android SDK requires AndroidX and does not support non-AndroidX apps. We suggest that you migrate your app to AndroidX.
- Why am I getting the error “Only role name allowed for in-person recipients” when using the SDK's useTemplateOnline() method?
This error indicates that the template was not set up properly. In the DocuSign web portal, make sure the Role is set for the recipient in the template. In the template, don't set any values in the Name, Host Name or Host Email fields. The recipient values will be prefilled with values from DSEnvelopeDefaults using the SDK method.
- When minifyEnabled is set to “true” in Proguard, why can’t I launch the signing session (useTemplateOnline() SDK method)?
You might be missing some Gradle-level configurations. Make sure to have the following line in your app’s build.gradle file:
android { buildTypes { release { ... proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro' } } } - When using a template, I prefilled the text field values using DSEnvelopeDefaults. Why are the values not showing up in the app during the signing session?
Make sure the template is set up correctly in the DocuSign web portal. A common mistake is that the text fields are mapped incorrectly to the intended recipient.
- How do I remove the Mobile friendly toggle button displayed in the online signing session?
If you want to disable mobile-friendly signing, you’ll need your account admin to turn it off in the account settings. In the DocuSign web portal, the admin should navigate to Signing Settings and then disable the option Allow recipients to view mobile-friendly documents with responsive signing.
- Can I disable the Mobile friendly toggle button displayed in the online signing session for a specific template?
Yes. In the DocuSign web portal, you can disable the responsive signing option for a particular template as follows:
- Select the template
- Edit the template
- Navigate to Message to All Recipients
- Select Advanced Options
- Select Edit
- Navigate to Mobile-Friendly Viewing with Responsive Signing
- Uncheck Allow recipients to view documents more easily on mobile devices
- Does the Android SDK support password-protected PDFs when creating envelopes for signing?
The Android SDK does not support password-protected PDFs for envelope preparation. You will need to remove the PDF’s password protection or encryption before using your document.
- Why am I getting the error “Unable to authenticate using provided access token” when using the SDK’s login() method with an access token?
Make sure to check whether the environment is set to demo or production.
If you’re using the demo environment, check that you set the environment after initializing the DocuSign instance as follows:
DocuSign.getInstance().setEnvironment(DSEnvironment.DEMO_ENVIRONMENT);If you’re using the production environment, check that you set the environment after initializing the DocuSign instance as follows:
DocuSign.getInstance().setEnvironment(DSEnvironment.PRODUCTION_ENVIRONMENT); - Why am I getting the error “Template Caching is not supported for <tab>” when caching a template using the SDK’s cacheTemplate() method?
If the template contains any of the tab types that are not supported by the Android SDK, remove those tabs from the template in the DocuSign web portal.
The Android SDK supports the following tab types:
- Signature
- Initials
- First Name
- Last Name
- Text
- Full Name
- Company
- Title
- Date Signed
- Checkbox
- List
- Radio
The Android SDK does not support the following tab types:
- Approve
- Decline
- Date
- Formula
- Envelope Id
- Note
- Notarize
- Number
- Signer Attachment
- SSN
- View
- Zip
- Email address
- Why am I getting the “Mobile signing disabled” error when caching a template using the SDK’s cacheTemplate() method?
In the DocuSign web portal, navigate to Settings and then select Signing Settings; make sure the Allow recipients to sign on a mobile device setting is enabled.
- Why am I getting the “User Account does not allow offline usage” error when caching a template using SDK cacheTemplate() method?
In the DocuSign web portal, navigate to Settings and then select Signing Settings; make sure the Allow offline signing on a mobile device setting is enabled.
- Why am I getting the “Recipient Offline Signing is disabled” error when caching a template using the SDK’s cacheTemplate() method?
In the DocuSign web portal, navigate to Settings and then select Signing Settings; make sure the Allow recipients to sign documents offline on a mobile device setting is enabled.
