How to request a signature using focused view

This topic demonstrates how to improve an embedded signing experience by using focused view. Focused view offers a minimal wrapper around the agreement document that shows only the agreement and a navigation button, making the experience look similar to embedding just the document within your web page.

Required data

Running the code in this how-to requires this data:

Step 1. Obtain your OAuth token

To make the API calls shown in this how-to, you need a valid OAuth access token. Docusign supports access tokens for three different recommended OAuth grant types: Public Authorization Code Grant, Confidential Authorization Code Grant, and JSON Web Token (JWT) Grant. Choose the OAuth grant type appropriate for your scenario.

Step 2. Create the envelope definition

The first step in requesting a signature within your app is to define a method (called makeEnvelope in our example) that creates the envelope definition using the following steps:

• Add a document to the definition by saving it to a variable as a binary-encoded base64 string. If you intend to attach multiple documents, specify the document order using an array. The order of the array sets the order of the documents.

• Set the signer’s data, including their name, email address, and a client user ID (any alphanumeric value is suitable). Including a client user ID automatically specifies the signer as embedded (using your app). If there are multiple signers, you must create a signer recipient for each one.

  Note: If the client user ID is set and either the SignerMustHaveAccount or SignerMustLoginToSign property of the account settings is set to true, the system throws an error.

• Create and assign signable fields (also known as tabs) for a specific signer within the document using AutoPlace. This how-to uses anchor tabs to generate tabs automatically in your document by searching for each occurrence of a specific string of characters in the document and adding tabs at those locations. This example uses the string “/sn1/” for auto-placing the signature (signHere) tab.

  To configure the anchor tabs, specify the number of units from the anchor text to offset the tab, as well as the string to search for and replace with a signHereTab within your document. You can create multiple signHere tabs for different locations and offsets, if needed.

  After creating the tabs, assign them to the signer created in the previous step.

• Set the envelope’s status property. To save the envelope as a draft, set status to created. To configure the envelope to be sent immediately after it is instantiated, set status to sent instead.

cat > "$request_data" <<EOF
{
    "emailSubject": "Please sign this document set",
    "documents": [
        {
            "documentBase64": "${doc1_base64_content}",
            "name": "Lorem Ipsum",
            "fileExtension": "pdf",
            "documentId": "1"
        }
    ],
    "recipients": {
        "signers": [
            {
                "email": "${SIGNER_EMAIL}",
                "name": "${SIGNER_NAME}",
                "recipientId": "1",
                "routingOrder": "1",
                "clientUserId": "1000"${identity_verification_json}
            }
        ]
    },
    "status": "sent"
}
EOF

Step 3. Call Docusign to create the envelope

With the envelope definition and the attributes defined for the signer, document, and custom fields, you can now use the Envelopes:create endpoint to create an envelope for the transaction.

• First, instantiate a new instance of the API client (if you’re using a Docusign SDK).
• Set the following default request header to add your access token to all API calls. "Authorization: Bearer ${ACCESS_TOKEN}"
• Initialize the Envelopes API.
• Using your Docusign integration key and the prepared envelope definition, generate and retrieve an envelope ID using the Envelopes:create endpoint.

create_envelope_http_status=$(curl --silent --show-error \
    --header "Authorization: Bearer ${ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --data-binary @"${request_data}" \
    --request POST "${base_path}/v2.1/accounts/${ACCOUNT_ID}/envelopes" \
    --output "${response}" \
    --write-out "%{http_code}")

Step 4. Create the recipient view definition for focused view

The recipient view is the screen that Docusign generates and displays in your app to enable your signers to sign documents. To create the definition for focused view, you must add the signer’s information, the return URL, the frameAncestors field, and the messageOrigins field.

• Set the return URL to which the user will be forwarded after signing is complete. For Focused View and Focused View Click to Agree, this property is required, but will not be used. Instead, the Docusign JS library will raise custom DOM events.

• To render the Click to Agree experience, create the envelope with no tabs assigned to the signer. When no tabs are present, focused view displays a simplified flow where the signer reviews the document and clicks a single Agree button to complete signing, rather than navigating through individual fields.

• To require phone-based identity verification before signing, add an identityVerification object to the signer when creating the envelope. This requires a workflowId and the signer’s phone number. The workflowId is specific to your account and can be retrieved from your account’s identity verification settings. When configured, the signer will be prompted to verify their identity via SMS before they can access the document for signing.

• Add the recipient information to the request, including the signer’s email, name, and clientUserID that were set for the recipient who will sign the envelope.

• Set the messageOrigins field to a single- element array: https://apps-d.docusign.com for the developer environment or https://apps.docusign.com for production environments.

• Add the frameAncestors field. Use only origins in this value. An origin includes a protocol (http or https) and a domain and may include a port. Do not include a path or a trailing slash. In production, only the HTTPS protocol is supported.

  These are valid frameAncestors values:

  • http://localhost:8080
  • https://apps-d.docusign.com

  These values are not valid:

  • http://localhost:8080/ (invalid due to the trailing slash)
  • https://apps-d.docusign.com/myapp/test (invalid due to the path appended to the origin)

  Include the origin or origins of the pages that will embed the focused view and the origin used in the messageOrigins field.

  Keep in mind that your domain must have a valid SSL certificate or an error message will be returned. We’re using the domain of the launcher, but make sure to replace this with your own domain name.

cat > "$request_data" <<EOF
{
    "returnUrl": "http://httpbin.org/get",
    "authenticationMethod": "none",
    "email": "${SIGNER_EMAIL}",
    "userName": "${SIGNER_NAME}",
    "clientUserId": 1000,
    "frameAncestors": ["http://localhost:8080", "https://apps-d.docusign.com"],
    "messageOrigins": ["https://apps-d.docusign.com"]
}
EOF

Step 5. Create the recipient view and initiate focused view signing

Next, create the recipient view. Use the EnvelopeViews:createRecipient endpoint, passing in your API account ID and the envelopeId and viewRequest objects generated in previous steps.

Finally, extract the url property from the JSON response. Send the url property to the JavaScript on the browser. Your JavaScript will use the url when it calls Docusign JS in the next step.

create_recipient_view_http_status=$(curl --silent --show-error \
    --header "Authorization: Bearer ${ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --data-binary @"${request_data}" \
    --request POST "${base_path}/v2.1/accounts/${ACCOUNT_ID}/envelopes/${envelope_id}/views/recipient" \
    --output "${response}" \
    --write-out "%{http_code}")

Step 6. Customize the focused view and embed it in a web page

Next, customize the focused view UI. You’ll need to load the Docusign JS library in order to turn on focused view. The URL for the JS library is https://js-d.docusign.com/bundle.js for the developer environment and https://js.docusign.com/bundle.js for the production environment.

The signing function takes a style parameter that can be used to customize styles and blend the agreement with the rest of your application:

Signing Navigation Button

• The position property takes one of three values: bottom-left, bottom-right, and bottom-center, which changes the placement of the signing button.
• The finishText property enables you to customize the text on the button when all the tabs have been completed and the agreement is ready to be signed.
• The shape property takes one of three values: default, sharp, or pill, which change the border radius of the signing button.

Signing Agree Button

• The finishText property enables you to customize the text on the agree button in the Click to Agree experience.

Signing Decline Button

• The show property controls whether the decline button is visible, allowing signers to decline to sign the envelope.
• the finishText property enables you to customize the text displayed on the decline button.
• The backgroundColor and color properties can be used to specify custom colors for the decline button.

Branding

• The primaryButton backgroundColor and color properties can be used to specify custom colors for the signing navigation button and primary buttons in the agreement.

Modals

• The downloadModal.show property controls whether a download modal is presented to the signer after signing is complete, enabling them to download a copy of the signed document.
• The declineModal.show property controls whether a confirmation modal is displayed when a signer chooses to decline.

Finally, create an HTML with div container to mount the signing URL. The iframe has a minimum height of 400px by default, but we’ve set it to 800px in this example.

-->
<br />
<h2>The document has been embedded with focused view.</h2>
<br />
<head>
    <meta charset=\"utf-8\" />
    <title>Signing</title>
    <style>
        html,
        body {
            padding: 0;
            margin: 0;
            font: 13px Helvetica, Arial, sans-serif;
        }
        .docusign-agreement {
            width: 75%;
            height: 800px;
        }
    </style>
</head>
<body>
    <div class=\"docusign-agreement\" id=\"agreement\"></div>
</body>
</html>
<script src='https://js.docusign.com/bundle.js'></script>
<script>
    window.DocuSign.loadDocuSign('" . $integrationKey . "')
        .then((docusign) => {
            const signing = docusign.signing({
                url: '" . $url . "',
                displayFormat: 'focused',
                style: {
                    /** High-level variables that mirror our existing branding APIs. Reusing the branding name here for familiarity. */
                    branding: {
                        primaryButton: {
                            /** Background color of primary button */
                            backgroundColor: '#50C878',
                            /** Text color of primary button */
                            color: '#fff',
                        }
                    },
                    /** High-level components we allow specific overrides for */
                    signingNavigationButton: {
                        finishText: 'You have finished the document! Hooray!',
                        position: 'bottom-center',
                        shape: 'pill',
                    },
                    signingAgreeButton: {
                        finishText: 'I Agree',
                    },
                    signingDeclineButton: {
                        show: true,
                        finishText: 'Decline',
                        backgroundColor: '#ff0000',
                        color: '#ffffff',
                    },
                    downloadModal: {
                        show: true,
                    },
                    declineModal: {
                        show: true,
                    },
                }
            });
            signing.on('ready', (event) => {
                console.log('UI is rendered');
            });
            signing.on('sessionEnd', (event) => {
                /** The event here denotes what caused the sessionEnd to trigger, such as signing_complete, ttl_expired etc../ **/
                console.log('sessionend', event);
                window.location.href = '/'
            });
            signing.mount('#agreement');
        })
        .catch((ex) => {
            // Any configuration or API limits will be caught here
        });
</script>
<!--

Expected response

If you run this code example from our Quickstart or launcher projects, you should see the agreement embedded in the results page of the example.

After signing is complete, the sender will receive a carbon copy (CC) of the email that includes all of the completed and signed documents.

Next steps

• Run this code example from our Quickstart or launcher projects: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.
• Learn more about Embedded signing.
• See all available eSignature How-to guides.
• See how to Go-Live with a completed app and find the base path for API calls in the production environment.