Embedded Signing Walkthrough

Give your users the ability to sign documents directly on your app or website using Dropbox Sign's embedded signing feature. The hellosign-embedded library adds the signing experience to your site using an iFrame. The documentation below describes requirements and setup steps for the embedded signing flow. Take a look at our premium branding guide to learn more about customizing your app's embedded signing.

Preliminary

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 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.

Server Side

The very first step is to create an embedded signature request from your backend using our API and then fetch the associated url that will be used in the iFrame. Note that embedded signature requests use a different endpoint than non-embedded signature requests. Endpoint: /signature_request/create_embedded

Creating an Embedded Signature Request

Generating a sign_url

Endpoint: /embedded/sign_url/{signature_id}

<?php

namespace Dropbox\SignSandbox;

require_once __DIR__ . '/../vendor/autoload.php';

use SplFileObject;
use Dropbox;

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();
$config->setUsername("YOUR_API_KEY");
// $config->setAccessToken("YOUR_ACCESS_TOKEN");

try {
    $response = (new Dropbox\Sign\Api\EmbeddedApi(config: $config))->embeddedSignUrl(
        signature_id: "50e3542f738adfa7ddd4cbd4c00d2a8ab6e4194b",
    );

    print_r($response);
} catch (Dropbox\Sign\ApiException $e) {
    echo "Exception when calling EmbeddedApi#embeddedSignUrl: {$e->getMessage()}";
}

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.

npm install hellosign-embedded

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

import HelloSign from 'hellosign-embedded';

const client = new HelloSign();

client.open(claimUrl, {
  clientId: 'Your API client ID',
  skipDomainVerification: true
});

{
  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
});

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

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.

Text Tags

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

Client Side 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
}