Embedded Requesting Walkthrough

Embedded Requesting allows you to have users create and send signature requests on your site in an iFrame using hellosign-embedded, Dropbox Sign’s official client-side library. The documentation below describes requirements and setup steps for the embedded requesting flow.

Preliminary

Please complete the steps below before following along with the content.

1. Create an API app (login required)

2. Save your API app’s Client ID and API Key, which you’ll need to use this feature.

Try Dropbox Sign Embedded

To get a feel for how our Dropbox Sign Embedded library works, you can use our Embedded Testing Tool to quickly test any of our Embedded flows without having to write a single line of JavaScript.

You can request a sample document, or use the custom edit_url that you’ll generate in the Server Side section below.

Server Side

The very first step is to create a “draft” signature request from the backend using our API. You must decide what you want to happen after the signature request is sent by your user. By default, Dropbox Sign will send an email to the signers and ask them to come to hellosign.com to sign and complete the document(s):

1
{
2
  "client_id": "b6b8e7deaf8f0b95c029dca049356d4a2cf9710a",
3
  "file_urls": [
4
    "https://www.dropbox.com/s/ad9qnhbrjjn64tu/mutual-NDA-example.pdf?dl=1"
5
  ],
6
  "requester_email_address": "jack@dropboxsign.com",
7
  "test_mode": true
8
}

Alternatively, you can use embedded requesting in conjunction with embedded signing by specifying the is_for_embedded_signing parameter. This will instruct Dropbox Sign to NOT email the signers and will allow you to decide when and how to display the embedded signing iFrame on your site.

In the aforementioned scenario, you will need to retrieve the signature url after the request has been sent using /embedded/sign_url. See the embedded signing walkthrough to learn how to construct the embedded signing page from that point on.

In this section, you created an Embedded Signature Request for jack@dropbox.com. When Jack accesses the embedded request, she’ll make edits to the signature request and send it out once complete. You’ll need to grab the claim_url from the JSON response. The claim_url is passed to the Client Side to use in Dropbox Sign Embedded’s open() method.

Client Side

We provide a client-side library that handles the authorization and display of the embedded request using an iFrame. You can use this feature by adding a few lines of JavaScript code.

If you are using a modern module bundler with npm, simply install hellosign-embedded.

$
npm install hellosign-embedded

If you are not using a modern module bunder like npm, our library can be downloaded manually, compiled from source, or imported from our CDN.

In your app, import the hellosign-embedded module, instantiate a new client, then invoke open() with your claimUrl and API client ID. Note that we’re using skipDomainVerification when calling this method. You can learn more about that in the Domain Restriction section below.

$
import HelloSign from 'hellosign-embedded';
$
$
const client = new HelloSign();
$
$
client.open(claimUrl, {
>
  clientId: 'Your API client ID',
>
  skipDomainVerification: true,
>
});

There are a number of options you can define as part of the second argument when calling open():

{
  “requestingEmail”: “alice@example.com”
}

{
  locale: HelloSign.locales.ZH_CN
}

{
  redirectTo: ‘http://example.com’
}

{
  allowCancel: false
}

{
  debug: true
}

{
  skipDomainVerification: true
}

{
  timeout: 10000
}

{
  container: document.getElementById(‘sign-here’)
}

Additional Notes

App Approval

In order to ensure that integrations adhere to eSignature regulations and best practices, an app approval is needed prior to moving into production for all customers implementing embedded signing, embedded requesting, embedded templates, and OAuth workflows.

Please refer to the App Approval Section for more detailed information about getting your app approved.

Domain Restriction

When the iFrame is loaded, it will verify the domain of the parent window and ensure it matches the domain name of the API app specified by the client ID. If the domain does not match, the page won’t be loaded.

You can disable domain restriction for easier development:

$
client.open(signUrl, {
>
  // ...
>
  skipDomainVerification: true
>
});

This will allow you to use development domains, like localhost. See the documentation for open() method in the section above.

HTTPS Required

The host page must be served over HTTPS. The iFrame is also loaded over HTTPS, and due to browser security restrictions it will not be able to communicate with the parent window if it is not HTTPS. This communication is required to enable features such as iFrame callbacks and closing the iFrame.

To make development easier, the page will still load if the parent window is served over HTTP, however an alert will be displayed to notify you of this requirement. Switch to HTTPS to prevent this alert from being displayed.

Redirection

If a redirect url is specified, the iFrame will redirect users to it after they send the document(s). Data from the send event will be appended to the url query string.

Text Tags

The embedded functionality can be used in conjunction with Dropbox Sign Text Tags.

Client Side Events

There are a number of events that the client may emit. To listen to these events, pass the event name and a callback function to on(). An string enumeration of available events can also be found under HelloSign.events.

$
client.on('sign', (data) => {
>
  console.log('The document has been signed!');
>
  console.log('Signature ID: ' + data.signatureId);
>
});

Here are a list of possible events:

{
  signatureRequestId,
  signatureRequestInfo {
    title,
    message,
    signatures,
    ccEmailAddresses
  }
}

{
  url,
  iFrameUrl
}

{
  type,
  payload
}

{
  signatureId,
  code
}