NOTE: This article is intended for HelloSign Embedded v2. As of August 2020, HelloSign Embedded v1 is no longer officially supported. If you are still using an older version of HelloSign Embedded, you can access a previous version of this article here.
Embedded requesting allows you to have users create and send signature requests on your site in an iFrame. The documentation below describes requirements and setup steps for the embedded requesting flow.
Before you start doing anything, make sure the following steps have been done:
1. Create an account if you don't already have one and retrieve your API key from the settings page. An Enterprise API plan is required to use Embedded Templates in production mode. Otherwise, you can only use it in test mode.
2.
Create an API app (login required)
To get a feel for how our HelloSign 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 by following the walkthrough below.
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, HelloSign will send an email to the signers and ask them to come to hellosign.com to sign and complete the document(s):
Alternatively, you can use embedded requesting in conjunction
with embedded signing by specifying the
is_for_embedded_signing
parameter. This will instruct HelloSign to NOT email the signers and will allow
you to decide when and how to display the embedded signing iFrame on your site.
In this 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.
NOTE If you'd like to specify the signers and CCs during this step (rather than let the user specify them when they edit and send the signature request), you can include the 'signers' and 'cc_email_addresses' parameters. See the unclaimed_draft/create_embedded documentation for more info.
Now that you've created an embedded signature request for jolene@example.com to edit
and send out, you need to grab the claim_url
from the JSON response. You will need to pass this claim_url
to
the Client Side to use
in HelloSign Embedded's open()
method.
We provide a library that takes care of building and displaying the iFrame on your page for you. It should only take you a few lines of JavaScript code to make this functional.
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, HelloSign Embedded 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.
import HelloSign from 'hellosign-embedded'; const client = new HelloSign(); client.open(claimUrl, { clientId: 'Your API client ID' });
NOTE It's recommended that you add the following to your
document's <head>
to avoid unexpected behavior on small screens.
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0">
There are a number of options you can define as part of the second argument when calling open()
:
Name | Type | Description |
---|---|---|
requestingEmail |
string |
The email of the account issuing the signature request.
NOTE: This option is only necessary for 'Me and Others' type signature requests.
Example:
{ requestingEmail: 'alice@example.com' } |
locale |
string |
The locale code that will be used to determine which language the embedded request will be displayed in. For a list of HelloSign's supported languages, visit our Languages page. If no locale is specified HelloSign will attempt to determine the user's preferred language by their browser settings or fall back to English.
NOTE: Czech ( CS_CZ ) is only supported by Embedded Signing.
Example:
{ locale: HelloSign.locales.ZH_CN } |
redirectTo |
string |
Where the user will be redirected after sending the signature request.
Example:
{ redirectTo: 'http://example.com' } |
allowCancel |
boolean |
Whether the user should be able to close the iFrame without finishing the request. Default: true .
Example:
{ allowCancel: false } |
debug |
boolean |
Allows debug output to print to the console. Default: false .For even more detailed debug output, run localStorage.debug = 'hellosign-embedded:*'; in your developer console and refresh the page.
Example:
{ debug: true } |
skipDomainVerification |
boolean |
Whether or not to skip the domain verification step. Default: false .
NOTE: This will only be honored if the signature request was created with test_mode=1 .
Example:
{ skipDomainVerification: true } |
timeout |
number |
How long (in milliseconds) to wait for the HelloSign app to initialize before aborting. Default: 30000 (30 seconds).
Example:
{ timeout: 10000 } |
container |
HTMLElement |
By default HelloSign Embedded will be opened in a modal, but by specifying container you can choose a DOM element on the page in which the iFrame will be embedded.
Example:
{ container: document.getElementById('sign-here') } |
In order to ensure that your integration adheres to eSignature regulations and best practices, we require a quick app review.
NOTE You will still be able to use your app in test mode until it gets approved. Only live/production activity requires approval.
1. Review our user identification requirements before adding Embedded Workflows into your website:
2. Email us at apisupport@hellosign.com to schedule an app review once your integration is complete and ready for production use.
3. Demonstrate your completed integration via screenshare (using a Google Hangout or Skype) by walking us through user account creation, email confirmation, and/or login on your website. We will also review your HelloSign integration as a whole to ensure proper functionality/to answer any questions that you may have. A review typically takes less than 30 minutes.
That's it! We’ll immediately approve your app (or make suggestions) after the review.
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 HelloSign Embedded on development domains, like localhost
.
See the documentation for HelloSign Embedded's open()
method for more information.
The host page must be served over HTTPS. The HelloSign 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.
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.
The embedded functionality can be used in conjunction with HelloSign Text Tags.
There are a number of events that the HelloSign Embedded 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:
Event | Description | Data |
---|---|---|
send |
Emitted when the user sends the signature request. | { signatureRequestId, signatureRequestInfo { title, message, signatures, ccEmailAddresses } } |
open |
Emitted when the HelloSign Embedded window has opened. | { url, iFrameUrl } |
cancel |
Emitted when the signature request was canceled by the user by either pressing the close button or selecting "close" from the dropdown list. | |
finish |
Emitted when the user has finished the embedded signature request flow without cancelling. However, the user may have declined or reassigned the signature request. | |
message |
Emitted when HelloSign Embedded has received a cross-origin window message from the HelloSign app. | { type, payload } |
close |
Emitted when the HelloSign Embedded window has closed. | |
error |
Emitted when the HelloSign app encounters an error. | { signatureId, code } |