SendSafely

Articles in this section

Building a Encrypted Web Form using the SendSafely Dropzone API

Follow

The SendSafely Dropzone API lets you easily build your own custom web form that uses end-to-end encryption to protect form data. If you are not already familiar with how our Dropzone API lets you build an encrypted web form, check out this blog post that provides an overview of how it works. 

If you've already read the post and are ready to implement your own web form, this article will guide you through the technical specifics of how to do so. We’ve also posted some live working examples on CodePen that you can use as a quick start template. 

This article assumes that you have a working knowledge of HTML and JavaScript. You don't need to be an all-star developer to build your own encrypted web form, but you will need a little bit of technical know-how. If you are not a developer or IT person but have one available, you may want to pull them in to help. 

Building the HTML

The HTML form is relatively simple, and can be styled however you choose. The only elements we care about are the actual form inputs. A very simple form example is shown below. This form asks the user to provide their email address, tax ID number, date of birth and also allows them to attach one or more files. 

<form id="dropzone_form" name="dropzone_form">
 <input type="email" id="email" name="email" placeholder="Email address"><br>
 <input id="secure_ssn" name="secure_ssn" placeholder="Tax ID Number (text will be encrypted)" type="text"><br>
 <input id="secure_dob" name="secure_dob" placeholder="Date of Birth (text will be encrypted)" type="text"><br>
 <div id="dropzone-placeholder-div"></div><br>
 <button id="sendsafely-submit" onclick="submitForm()" type="button">Submit</button>
</form>

 There are a few key points to note about the form HTML shown above:

  • The HTML form is given a unique ID and Name of “dropzone_form”. This will make it easy for us to reference this form from JavaScript later on in the example.

  • There are three text inputs on the form: Email, Tax ID, and Date of Birth. Those inputs are also each given a unique ID and Name of “email”, “secure_ssn” and “secure_dob” respectively.

  • The email value will NOT be encrypted since we will use that value to identify the user who submitted this information. The Tax ID and Date of Birth fields WILL be encrypted, which is why we preface the ID and Name values with “secure_”. This will make it easy for our Javascript to distinguish which form elements require encryption.

  • The “dropzone-placeholder-div” element is a placeholder where we want to render the drag-and-drop interface for users to attach encrypted files. If you do not want users to attach files, that element is not necessary.

  • When the form’s Submit button is pressed, we will invoke a custom JavaScript function called “submitForm()”.

Adding JavaScript

Next, we will take a look at some JavaScript that needs to be added to the page in order for the form to work properly. There are two main pieces of JavaScript code:

  • A routine that initializes the Dropzone API when the page loads
  • A function that gets called when the user presses the Submit button

Initialization JavaScript

The initialization JavaScript should be placed at the top of your page and should look something like the following:

<script>
var widget;
var sendSafelyHost = "https://mycompany.sendsafely.com";
var dropzoneId = "1234567890ABCDEF1234567890ABCDEF";
$(document).ready(function() {
 var placeholderElement = $("#dropzone-placeholder-div");
 widget = new SendSafelyDropzone(dropzoneId, placeholderElement);
 widget.url = sendSafelyHost;
 widget.initialize();
});
</script>

 There are a few key points to note about the JavaScript shown above:

  • There are three variables that are declared at the top of the script, which are accessible to all functions on the page (widget, sendsafelyHost and dropzoneId). You should replace the sendsafelyHost and dropzoneId with the hostname of your SendSafely portal (i.e., companyname.sendsafely.com) and your unique Dropzone ID. Your Dropzone ID can be obtained from the SendSafely "Edit Profile" screen once you enable your Dropzone. Steps on how to enable and configure the Dropzone can be found here. 

  • The code within document.ready() initializes the SendSafely widget using the Dropzone ID and references the unique placeholder DIV element from your HTML form.

Form Processing JavaScript 

Last, you must define the JavaScript function that fires when the user presses the Submit button so that the form can be processed. This block of code includes a total of three functions:

  • submitForm - The function that is invoked when the user presses the Submit button.

  • buildSecureMessage - A utility function to parse the encrypted form fields and build the secure message payload (called by submitForm).

  • submitHostedDropzone - A utility function to invoke an endpoint on the SendSafely server that will handle notifications as defined in your Hosted Dropzone configuration settings (called by submitForm). Refer to this article for information on the different notification options and how to configure them. 

The code for these functions are below.

<script>
function submitForm() {
 var secureMessage = buildSecureMessage();
 widget.setUnconfirmedSender(
   $("#email").val().toLowerCase()
 );
 widget.addMessage(secureMessage);
 widget.finalizePackage(
   function(url) {
     submitHostedDropzone(url);
 });
}

function buildSecureMessage() {
 var secureMessage = "";
 $("#dropzone_form input[type=text]").each(function() {
   if (this.name.startsWith("secure_")) {
     secureMessage += $(this).attr("id") + ": " + this.value + "\n";
   }
 });
 return secureMessage;
}

function submitHostedDropzone(url) {
 var postData = {};
 postData["name"] = $("#name").val();
 postData["email"] = $("#email").val();
 postData["packageCode"] = widget.packageCode;
 postData["publicApiKey"] = dropzoneId;
 $.post(
   sendSafelyHost + "/auth/json/?action=submitHostedDropzone",
   postData,
   function(result) {
     if (result.integrationUrls !== undefined) {
       for (i = 0; i < result.integrationUrls.length; i++) {
         var integrationUrl = result.integrationUrls[i];
         //Third party form integration...do post to URL
         var postData = {};
         postData["digest"] = result.digest;
         postData["data"] = result.data;
         postData["secureLink"] = url;
         $.post(
           integrationUrl,
           postData,
           function(json) {
             if (json.error != undefined) {
               alert(json.error);
             } else {
               //success
               alert("Your information has been submitted.");
               window.location.reload();
             }
           },
           "json"
         );
       }
     }
   }
 );
}
</script>

A few points to note about the above functions:

  • The submitForm() function builds the secure message payload using buildSecureMessage() (see below for more information) and then calls the finalize() method to finalize the SendSafely pacakge. After the package is finalized, this function calls the submitHostedDropzone() function to handle notifications as configured for your Hosted Dropzone. The use of submitHostedDropzone() is optional but recommended unless you have your own endpoint that is capable of handling notifications for you.

  • The buildSecureMessage() function collects each name/value pair in the format “name: value” and compiles them into a SendSafely secure message payload separated by a new line between each pair. You have complete control over how the inputs are formatted and stored within SendSafely. For example, if you wanted store these values as JSON you could use $('#formid').serializeArray();

  • The submitHostedDropzone() function calls an endpoint on the SendSafely server that performs Drozpone notifications as they are configured for your Hosted Dropzone. This function should generally not be modified as it is designed to perform the exact same notifications that would happen when an item was submitted to your Hosted Dropzone. If you prefer to perform your own notification, you can omit this function and handle the secure link using your own custom endpoint.

Putting it all together

The complete HTML form and JavaScript are included below. Keep in mind that this example is minimalist and does not include and CSS styling or UI validation.

For more robust examples that can be adapted for use, check out our sample code posted on CodePen. 

<html>
<script src="https://code.jquery.com/jquery-3.3.1.js"></script>
<script src="https://app.sendsafely.com/js/external/SendSafelyDropzone.js" type="text/javascript"></script>
<form id="dropzone_form" name="dropzone_form">
 <input type="email" id="email" name="email" placeholder="Email address"><br>
 <input id="secure_ssn" name="secure_ssn" placeholder="Tax ID Number (text will be encrypted)" type="text"><br>
 <input id="secure_dob" name="secure_dob" placeholder="Date of Birth (text will be encrypted)" type="text"><br>
 <div id="dropzone-placeholder-div"></div><br>
 <button id="sendsafely-submit" onclick="submitForm()" type="button">Submit</button>
</form>
<script>
function submitForm() {
 var secureMessage = buildSecureMessage();
 widget.setUnconfirmedSender(
   $("#email").val().toLowerCase()
 );
 widget.addMessage(secureMessage);
 widget.finalizePackage(
   function(url) {
     submitHostedDropzone(url);
 });
}
 
function buildSecureMessage() {
 var secureMessage = "";
 $("#dropzone_form input[type=text]").each(function() {
   if (this.name.startsWith("secure_")) {
     secureMessage += $(this).attr("id") + ": " + this.value + "\n";
   }
 });
 return secureMessage;
}
 
function submitHostedDropzone(url) {
 var postData = {};
 postData["name"] = $("#name").val();
 postData["email"] = $("#email").val();
 postData["packageCode"] = widget.packageCode;
 postData["publicApiKey"] = dropzoneId;
 $.post(
   sendSafelyHost + "/auth/json/?action=submitHostedDropzone",
   postData,
   function(result) {
     if (result.integrationUrls !== undefined) {
       for (i = 0; i < result.integrationUrls.length; i++) {
         var integrationUrl = result.integrationUrls[i];
         //Third party form integration...do post to URL
         var postData = {};
         postData["digest"] = result.digest;
         postData["data"] = result.data;
         postData["secureLink"] = url;
         $.post(
           integrationUrl,
           postData,
           function(json) {
             if (json.error != undefined) {
               alert(json.error);
             } else {
               //success
               alert("Your information has been submitted.");
               window.location.reload();
             }
           },
           "json"
         );
       }
     }
   }
 );
}
</script>

<script>
var widget;
var sendSafelyHost = "https://mycompany.sendsafely.com";
var dropzoneId = "1234567890ABCDEF1234567890ABCDEF";
$(document).ready(function() {
 var placeholderElement = $("#dropzone-placeholder-div");
 widget = new SendSafelyDropzone(dropzoneId, placeholderElement);
 widget.url = sendSafelyHost;
 widget.initialize();
});
</script>
</html>

If you are a current SendSafely customer and would like assistance implementing your own custom web form, email us at support@sendsafely.com for help. 

 

Related articles

Comments

0 comments

Please sign in to leave a comment.