For a little over a year, we at HelloSign have been building and testing a brand new version of our HelloSign Embedded library. Built from the ground up, this new version is designed to be much more robust and developer friendly with modern web standards and APIs in mind.
What is HelloSign Embedded?
Before we get into how V2 improves on the old version, it's first important to understand what exactly HelloSign Embedded is.
HelloSign Embedded is not what is seen inside of the modal when you or one of your users is signing or editing a signature request. Marking up documents, inserting signatures, or entering data into text fields are all done in an embedded iFrame which points to app.hellosign.com. It’s a common misconception that the code that makes it all work lives in HelloSign Embedded, but in reality it’s all hosted on the HelloSign webapp at app.hellosign.com.
HelloSign Embedded is simply a set of tools which allows you, as a developer, to embed signature requests created using the HelloSign API within your own website. It is only responsible for opening the signature request on app.hellosign.com within an iFrame, resizing and positioning the modal, as well as interpreting, delegating, and responding to messages sent by the HelloSign webapp.
With the exception of the close button and the modal container, HelloSign Embedded's footprint is invisible. It is merely a wrapper around the HelloSign webapp which allows embedding HelloSign signature requests within your own website quick and easy.
More intuitive and predictable APIs
This was a bit clunky. Now, with the new version of HelloSign Embedded you instead simply bind an event listener of the desired type to the client instance.
No longer a singleton
HelloSign Embedded has historically been a singleton—only one instance could exist on the page at any given time.
If it helps, we've created a few projects to help you get started with HelloSign Embedded v2. You can find them here.
Better version control management
So with the new version of HelloSign Embedded, we've changed how the CDN works. We still offer a CDN version of our library—available through our official CDN—but we will no longer offer a similar “latest” version. Instead our users can import a specific version of HelloSign Embedded by simply entering the version name as part of the resource path. You can see an example of this below, where we’re importing version v2.6.0.
To update the version of HelloSign Embedded, just change the version number. After every release, we publish our latest CDN links on our GitHub wiki here.
HelloSign Embedded v2 now has an improved debugging system via debug. These debug messages are very comprehensive and cover most actions that HelloSign Embedded takes, allowing you to easily troubleshoot and diagnose issues. However, the debugger messages are not enabled by default. To enable HelloSign Embedded debugging for your current domain, you'll need to update your local storage. To do this, open up your browser's developer console, enter the following, then hit return:
Refresh the page, and now HelloSign Embedded will write debug messages to the developer console. For a complete signature request flow, it should look something like this:
From now on (until you clear your website data) any HelloSign Embedded instance that lives on this domain will send debug messages to your web console. If you want to debug HelloSign Embedded on a new domain—say if you were testing on localhost originally but now want to debug on production—you’ll need to enter that command into your console again.
If you’d like to try HelloSign Embedded, feel free to check out our starter projects to get you up and running. The HelloSign Embedded wiki is also a valuable resource, take a look at our quickstart guide which will help you create your first signature request and embed it in your web app.
If you already have a pre-existing implementation of HelloSign Embedded v1, don’t worry, upgrading to Embedded v2 should be relatively straightforward. For most simple implementations, it should only take a few minutes. Check out our v1 to v2 migration guide for more information, or reach out to our API Support team at firstname.lastname@example.org, where one of our API Support Engineers will be happy to help you.
And if you find a problem, please reach out to us or open an issue on the HelloSign Embedded GitHub repository. Your contributions and feedback are essential in helping us build better tools for for you and your users.