Migration Guide (v1 to v2) - hellosign/hellosign-embedded GitHub Wiki

• Background
• Notable Changes
• TL;DR

Initially released in early 2016, HelloSign Embedded is a major part of HelloSign's offering, with thousands of active users every day. However, over the years, the code had become difficult to maintain, and adding new features often resulted in regression or new bugs. It was then decided that it would be rebuilt from the ground up using modern web standards and syntax, improved testing, improved documentation, and improved capability.

From a high level, there are a few notable differences between v1 and v2:

• The HelloSign v1 CDN is now legacy.

  If you installed HelloSign Embedded v1 via our CDN:

  <script type="text/javascript" src="https://s3.amazonaws.com/cdn.hellosign.com/public/js/hellosign-embedded.LATEST.min.js"></script>

  It will no longer be updated. This is because modifying hellosign-embedded.LATEST.min.js will introduce breaking changes to thousands of users because LATEST has no adequate versioning control system. Instead, we highly recommend you install our hellosign-embedded package from npm. If this is not an option for you, HelloSign Embedded v2 will be available via a new CDN, but we cannot guarantee uptime.

• HelloSign is now a class, not a singleton.

  In v2, you must instantiate a new HelloSign Embedded client in order to call open(). Instantiating a new client is akin to calling init() in HelloSign Embedded v1.

  - HelloSign.init('Your client id');
  
  + const client = new HelloSign({
  +   clientId: 'Your client id'
  + });

• The url option has been moved.

  The url option was always required, so it didn't make sense to have it as an option. Now, pass the url into open() as its first argument.

  - HelloSign.open({
  -   url,
  -   // ...
  - });
  
  + client.open(url, {
  +   // ...
  + });

• The messageListener option has been removed.

  Instead the client instance emits a number of events. See API Documentation for more information.

  - HelloSign.open({
  -   // ...
  -   messageListener(evtData) {
  -     if (eventData.event == HelloSign.EVENT_SIGNED) {
  -       console.log('The signature request was signed!');
  -     }
  -   }
  - });
  
  + client.on(HelloSign.events.SIGN, () => {
  +   console.log('The signature request was signed!');   
  + });

  It's important to note that in v2, the event listeners are tied to the client, and not an individual iFrame created by client.open(). This means that you will likely want to disconnect your event listeners from your client.open() calls, otherwise you may experience unexpected behavior.

  Here is an example of code to avoid:

  function launchHelloSign(url) {
    client.on('open', () => {
      console.log('client opened');
    });
  
    client.open(url);
  }
  
  launchHelloSign(url);

  The reason why the above is not ideal, is because if your app can call client.open() more than once, the 'open' event listener will be applied twice. In the example above, if launchHelloSign() is called a second time, then "client opened" will be logged two more times, a total of three times. Further, calling launchHelloSign() a third time will log "client opened" a total of six times, despite only having been opened three times.

  To avoid this, there are few ideal solutions:

  1. Disconnect your event listeners from your client.open() calls:

     client.on('open', () => {
       console.log('client opened');
     });
     
     function launchHelloSign(url) {
       client.open(url);
     }
     
     launchHelloSign(url);

  2. Unbind event listeners once they've been called.

     function launchHelloSign(url) {
       client.once('open', () => {
         client.off('open');
         console.log('client opened');
       });
     
       client.open(url);
     }
     
     launchHelloSign(url);

  3. Essentially equivalent to the above, use once() instead of on(), which creates an an event listener which is only called once, and then discarded.

     function launchHelloSign(url) {
       client.once('open', () => {
         console.log('client opened');
       });
     
       client.open(url);
     }
     
     launchHelloSign(url);

• The uxVersion option has been removed.

  It was a stop-gap solution needed to support multiple versions of HelloSign Embedded. It is now deprecated.

• The height option has been removed.

  The HelloSign Embedded iFrame now defaults to 100% height. To change it's height, just change the height of it's container.

• The open() method now takes two arguments.

  The url used to be defined in the options object, however being that it's a required property it has been made into its own parameter. The second parameter for open() is now where the options object lives.

  - HelloSign.open({
  -   url,
  -   debug: true
  - });
  
  + client.open(url, {
  +   debug: true
  + });

• The viewport meta tag is no longer automatically added to the document head.

  In older versions of HelloSign Embedded, the following tag was automatically added to the <head> of the document.

  <meta name="viewport" content="width=device-width, initial-scale=1.0">

  This meta tag forces your website to be mobile friendly so that HelloSign Embedded renders properly on mobile devices. We decided that injecting meta tags into your document's head was bad practice, and instead the onus of making a website responsive on mobile should fall to the website developer, rather than a 3rd-party library like HelloSign Embedded. If you want your users to have a nice experience signing when on a mobile device, simply adding the above tag to your <head> should do the trick.

• A few options have been renamed.

  • userCulture is now locale
  • healthCheckTimeoutMs is now timeout
  • whiteLabelingOptions is now whiteLabeling
  • requester is now requestingEmail
  • redirectUrl is now redirectTo

• Static properties have moved

  • An enum of language codes can now be found at HelloSign.cultures.
  • An enum of events can now be found at HelloSign.events.

The gist of it is:

HelloSign.init(clientId);

HelloSign.open({
  url,
  skipDomainVerification: true,
  messageListener(evtData) {
    if (eventData.event == HelloSign.EVENT_SIGNED) {
      console.log('The signature request was signed!');
    }
  }
});

const client = new HelloSign({ clientId });

client.open(url, {
  skipDomainVerification: true
});

client.once(HelloSign.events.SIGN, () => {
  console.log('The signature request was signed!');   
});