Skip to navigation
eSignature API 101eSignature conceptsEmbedding Docusign eSignature

Docusign JS for embedded signing reference

View as Markdown

You can use the Docusign JS JavaScript library to:

  • Implement Embedded signing with focused view, focused view/Click to Agree, and classic signing sessions.
  • Render web form instance URLs for the Docusign Web Forms API.

This topic focuses on using Docusign JS for embedded signing. See Web Forms API when using it with the Web Forms API. The library can be used for both purposes on the same web page.

1. Install Docusign JS

Add the development or production version of Docusign JS to your web page:

  • If your app uses the Development environment: <script src="https://js-d.docusign.com/bundle.js"></script>
  • If your app uses the Production environment: <script src="https://js.docusign.com/bundle.js"></script>

Note: Do not make a local copy of bundle.js, it must match the platform version.

2. Add a container element to your DOM

When the Docusign JS mount method is called, it will add an iframe to the DOM element you use as an argument for the method. When the sessionEnd event is raised, the library will delete the iframe.

Add an empty block element (such as a div) to your DOM to hold the iframe. You must set the block element’s width and height. You can use @media CSS to change the div’s width based on the overall screen’s width. Bootstrap and other layout systems can also be used.

Example container element
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Signing</title>
    <style>
      html, body {
        padding: 0;
        margin: 0;
        font: 13px Helvetica, Arial, sans-serif;}
        /* container styles */
        @media (max-width: 768px){
          .docusign-agreement-container {width: 50%}}
        @media (min-width: 769px) (max-width: 1024px) {
          .docusign-agreement-container {width: 70%}}
        @media (min-width: 1025px) {
          .docusign-agreement-container {width: 100%}}
    </style>
  </head>
  <body>
    <header><h1> Demo</h1></header>
    <div class="docusign-agreement-container" id="docusignContainer"></div>
  </body>
</html>

3. Call EnvelopeViews:createRecipient

Call the EnvelopeViews:createRecipient API method and provide values for the frameAncestors and messageOrigins attributes:

  • The frameAncestors attribute is an array of HTTP origin strings, not including anything after the hostname or port. Include the https://apps-d.docusign.com origin for the developer environment or https://apps.docusign.com for production. Include additional origins for your app’s ancestor origins that will embed the signing session. Origins must use https rather than http, with the exception of for localhost. The localhost origin can’t be used in production.

    Note: frameAncestors has a limit of 500 characters (for all URLs combined).

    Examples:

    ["https://apps-d.docusign.com", "http://localhost"] # default port
    ["https://apps-d.docusign.com", "http://localhost:8080"] # specific port
    ["https://apps.docusign.com", "https://app1.example.com",
    	"http://app1frame.example.com"] # production

  • The messageOrigins attribute is an array of HTTP origin strings. The array must have one member:

    • ["https://apps-d.docusign.com"] # demo
    • ["https://apps.docusign.com"] # production

  • The returnUrl attribute must be set, but will not be used.

All other attributes should be set as usual.

The EnvelopeViews:createRecipient API method’s url response is used in the browser with Docusign JS. If you call createRecipient on the server, return the url to your browser page.

The window.loadDocuSign(``integration_key``) RETURNS Promise resolves to a Docusign object, and is called first to obtain the Docusign object.

Performance tip: This method can be called asynchronously before it is needed to create a signing session.

The integration_key argument is a string that contains your application’s integration key (client ID). Client IDs are not secrets.

Signing method

The Docusign object includes the signing method:

signing(SigningConfiguration) RETURNS Signing object

The signing method creates the embedded signing session. It takes as a parameter a SigningConfiguration object to control the signing session’s format and style attributes. The returned Signing object represents the signing session that will be displayed. See Signing object methods for a list of methods.

SigningConfiguration object properties

Property nameTypeDescription
urlstringRequired. The signing URL response from EnvelopeViews:createRecipient.
displayFormatstringRequired. The signing session’s UX format.
Possible values are:
  • "focused": Sets the signing session to use focused view or (if the main documents have no tabs) focused view/Click to Agree
  • "default": Sets the signing session to use the Docusign classic UX format.
styleStyleObject objectOptional. A StyleObject containing style settings for the signing session.

StyleObject properties

Some styling options have not yet been implemented for some display formats.

{
 branding: BrandingObject,
 signingNavigationButton: SigningNavigationButtonObject
}

The following options are supported for the Docusign JS StyleObject:

Property nameTypeDescription
brandingBrandingObjectA container for objects on which branding style elements can be applied. Currently this consists of the primaryButton object.
primaryButton (sub-object of branding)PrimaryButtonObjectSettings for the primary UX button.
Properties:
  • color: CSS color value for the text of the button.
  • backgroundColor: CSS color value for the button itself.
signingNavigationButtonSigningNavigationButtonObjectOptional; specifies position and text for the signing button.

Properties:
  • finishText: String with a maximum of 50 characters.
  • position: Accepts one of these values: 'bottom-left', 'bottom-center', 'bottom-right'.
signingDeclineButtonsigningDeclineButtonObjectOptional; specifies if a Decline button will be shown. This option is not available for all display formats.

Properties:
  • show: A boolean value that indicates whether to show a Decline button or not. If false (default), do not show a Decline button. If true, show a Decline button. See Decline and Approve tab types for more information.
  • finishText: String with a maximum of 50 characters that will render on the signingDeclineButton
declineModaldeclineModalObjectOptional; show indicates whether to show a Decline modal or not to require a reason to decline or to decline immediately. Defaults to false.
downloadModaldownloadModalObjectOptional; show indicates whether to show a download completed document modal after envelope finish. Defaults to false.

Example SigningConfiguration object

const signingConfiguration = {
    url: recipientViewUrl,
    displayFormat: 'focused',
    style: {
        branding: {
            primaryButton: {
                backgroundColor: 'purple',
                color: 'white'
            }
        },
        signingNavigationButton: {
            finishText: 'Submit',
            position: 'bottom-right'
        },
        signingDeclineButton: {
            show: true, // default value is false
            finishText: 'Decline Button Text'
        },
        declineModal: {
            show: true // default value is false
        },
        downloadModal: {
            show: true // default value is false
        }
    }
}

Signing object methods

The signing object is used to display the signing session and catch the signing-related events it raises.

Method nameDescription
mount(containerSelectString)Adds, then displays the signing session to the DOM. This is a synchronous method that initiates asynchronous side effects (the signing session is displayed). The ready event is raised when the session has been displayed.
The required containerSelectString parameter is a CSS selector string that resolves to the container element for the signing session. For example: "#docusignContainer"
on(eventName, cbFunction)The on method adds an event listener. - The required cbFunction parameter is a function with an event argument. - The required eventName parameter is a string naming the event. The following events are supported as eventName argument values: - ready: The signing session has been displayed and is ready for the user - sessionEnd: The signing session has ended. There are multiple reasons for this event, for which the event.sessionEndType string will be set: text 'signing_complete' 'cancel' 'decline' 'exception' 'fax_pending' 'session_timeout' 'ttl_expired' 'viewing_complete'

Use Docusign JS with JavaScript

This example uses the JavaScript module type to enable the await keyword at the top level of the script.

<style>
    .hide {display: none;}
</style>
...
<script type="module">
    let signingUrl; // the EnvelopeViews:createRecipient response
    let clientId; // your app’s IK
    const signingConfiguration = {
        url: signingUrl,
        displayFormat: 'focused',
        style: // see above for an example
    }
    try {
        const docusign = await window.DocuSign.loadDocuSign(clientId);
        const signing = docusign.signing(signingConfiguration);
        /** Event handlers **/
        signing.on('ready', (event) => {console.log('UI is rendered')});
        signing.on('sessionEnd', (event) => {
            console.log('sessionEnd', event)});
        // Open the signing ceremony
        $(`#main`).addClass("hide"); // JQuery to hide content
        $(`#signing-ceremony`).removeClass("hide"); // Display the container
        signing.mount(`#signing-ceremony`);
    } catch (error) {
        // Any configuration or API limits will be caught here
        console.log ("### Error calling docusign.js");
        console.log (error);
    }
</script>