Embedded Templates Walkthrough

Embedded templates allow your users to create and edit templates on your site in an iFrame using hellosign-embedded, Dropbox Sign’s official client-side library. Templates are used to make frequently-used documents easier to send for signatures and share with others. They’re also a powerful tool for automating workflows and using pre-filled data in your signature requests.

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 claim_url or edit_url that you’ll generate in the Server Side section below.

Server Side

Allowing your site users to create a template involves first creating a template draft. This draft will be displayed on your site in an embedded iFrame, allowing the user to edit and finalize the template. Note that templates created via the embedded template process will only be accessible through the API.

Creating a Template

1
{
2
  "client_id": "37dee8d8440c66d54cfa05d92c160882",
3
  "file_urls": [
4
    "https://www.dropbox.com/s/ad9qnhbrjjn64tu/mutual-NDA-example.pdf?dl=1"
5
  ],
6
  "title": "Test Template",
7
  "subject": "Please sign this document",
8
  "message": "For your approval",
9
  "signer_roles": [
10
    {
11
      "name": "Client",
12
      "order": 0
13
    },
14
    {
15
      "name": "Witness",
16
      "order": 1
17
    }
18
  ],
19
  "cc_roles": [
20
    "Manager"
21
  ],
22
  "merge_fields": [
23
    {
24
      "name": "Full Name",
25
      "type": "text"
26
    },
27
    {
28
      "name": "Is Registered?",
29
      "type": "checkbox"
30
    }
31
  ],
32
  "field_options": {
33
    "date_format": "DD - MM - YYYY"
34
  },
35
  "test_mode": true
36
}

1
{
2
  "template": {
3
    "template_id": "c26b8a16784f872a37ffa032f10d1c7c",
4
    "edit_url": "https://app.hellosign.com/editor/embedded?token=1234567890abcdef",
5
    "expires_at": 1234567890
6
  }
7
}

$
npm install hellosign-embedded

$
import HelloSign from 'hellosign-embedded';
$
$
const client = new HelloSign({
>
  clientId: 'Your API client ID'
>
});

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

Pre-filled Data

By creating a template draft with merge fields, you are essentially telling your users, “The app can supply this information for you when you use the completed template to send a signature request.”

This can be useful if, for example, your app stores contact information. If a user sends a signature request to one of the contacts in your system, you can pre-populate the signature request with contact details prior to sending. It’s necessary to provide these details as ‘merge fields’ during the template creation because it indicates where the data should be placed within the document when sending the signature request.

As explained in the creating a template section, merge fields are specified during the template draft creation API request as a JSON array. Each merge field must have a unique name, and this is enforced by the API.

When the user is presented with the template draft editor, they are allowed to place these merge fields in the document. Merge fields appear to the user as standard Textbox and Checkbox fields. When one of these fields is placed on the document, the context menu will display the app as an option for the data source (in the “Who fills this out?” dropdown list), and the names of any pre-defined merge fields are listed in the dropdown underneath “What text goes here?”.

Once the template is saved, the data to populate these merge fields can be specified in the API call to create a signature request. This not only saves the user time, but also ensures better data accuracy. To populate the merge fields, simply execute a /signature_request/send_with_template and use the custom_fields parameter, or supply the same parameter when creating an embedded draft for previewing (see previewing a signature request below).

Editing a Template

If a template was created using Embedded Templates, then you can also allow your users to edit it by calling /embedded/edit_url/{template_id} and opening the edit_url with hellosign-embedded. At the time of writing, you cannot use Embedded Templates to edit a template created on hellosign.com.

1
{
2
  "cc_roles": [
3
    ""
4
  ],
5
  "merge_fields": []
6
}

1
{
2
  "embedded": {
3
    "edit_url": "https://app.hellosign.com/editor/embedded?token=1234567890abcdef",
4
    "expires_at": 1234567890
5
  }
6
}

1
client.open(editUrl, {
2
  skipDomainVerification: true
3
});

Previewing a Signature Request

When your site user needs to send a signature request based on a template, you will need to create an embedded signature request draft. This draft can be opened in an embedded iFrame to allow the user to preview the request prior to sending. Creating the signature request draft for previewing is also a perfect opportunity to populate any pre-defined merge fields that might have been added by the user during the template creation process.

1
{
2
  "client_id": "b6b8e7deaf8f0b95c029dca049356d4a2cf9710a",
3
  "template_ids": [
4
    "61a832ff0d8423f91d503e76bfbcc750f7417c78"
5
  ],
6
  "requester_email_address": "jack@dropboxsign.com",
7
  "signers": [
8
    {
9
      "role": "Client",
10
      "name": "George",
11
      "email_address": "george@example.com"
12
    }
13
  ],
14
  "ccs": [
15
    {
16
      "role": "Accounting",
17
      "email_address": "accounting@dropboxsign.com"
18
    }
19
  ],
20
  "test_mode": false
21
}

1
{
2
  "unclaimed_draft": {
3
    "claim_url": "https://app.hellosign.com/editor/embedded?token=1234567890abcdef",
4
    "expires_at": 1234567890
5
  }
6
}

1
client.open(editUrl, {
2
  skipDomainVerification: true
3
});

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 sign event will be appended to the url query string.

Signature Links

Signature URLs are only valid for 60 minutes after /embedded/sign_url has been called and expire as soon as they’re accessed.

It is best practice to wait until your signer hits the page before generating the sign_url so the link doesn’t expire before the signer is ready. However, since the signature_id itself does not expire, a fresh sign_url can always be generated.

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:

{
  templateId,
  templateInfo {
    title,
    message,
    signerRoles,
    ccRoles
  }
}

{
  url,
  iFrameUrl
}

{
  type,
  payload
}

{
  signatureId,
  code
}