BoloSign Embedding System Documentation

Introduction

BoloSign’s embed feature enables seamless integration of digital signature functionality into your website or application, streamlining document workflows and improving client signing experiences.

Overview

The BoloSign embed feature allows you to request digital signatures on documents directly within your app. This embedded HTML/JavaScript interface supports multiple signers, webhooks for tracking, and customizable contact details, making it ideal for embedding document signing workflows.

Basic Setup

To set up BoloSign’s embed feature, first include the CDN script and then configure the embed instance as shown below:

<script src="https://appscript-scripts.s3.ap-south-1.amazonaws.com/boloforms-embed-index.min.js"></script>

Here’s a basic configuration example that can be customized for your web application:

let config = {
  containerId: "embed-container",  // ID of the container where the iframe will load
  token: "your-embed-key",         // Embed key from Settings > Developer Section > Embed
  iframeOpts: { width: "100%", height: "600px" },
  sessionInfo: "123-john-doe",     // Optional, used to identify the user and manage contact caching
  contacts: {                      // Optional, pre-populates contact data
    data: [
      {
        firstName: "John",
        lastName: "Doe",
        email: "[email protected]",
        phone: "+1234567890",
        company: "Acme Corp",
        jobTitle: "Software Engineer",
        streetAddress: "123 Main St",
        city: "Metropolis",
        postalCode: "12345",
        country: "USA",
        state: "NY",
        customFields: { preferredContactMethod: "email", customerId: 12345 },
      },
    ],
  },
};
let embed = new BoloFormsEmbed(config);

Functions and Methods Explanations

Here’s a list of primary functions and methods exposed by BoloFormsEmbed for interacting with the embedded signing interface:

`embed.createPDF()`

Description: Initiates the process to create a new PDF document within the embed instance.
Usage:
```
embed.createPDF();
```

`embed.destroy()`

Description: Destroys the current embed instance, releasing resources and removing the interface.
Usage:
```
embed.destroy();
```

`embed.reloadIframe()`

Description: Reloads the embedded iframe to reflect any updates.
Usage:
```
embed.reloadIframe();
```

`embed.openDocument(documentId)`

Description: Opens an existing document within the embed interface using its unique documentId.

Usage:

embed.openDocument("your-document-id");

`embed.setSessionInfo(sessionInfo)`

Description: Updates the session information to track user-specific data and segregate contacts.

Usage:

const sessionInfo = { key: "value" };
embed.setSessionInfo(sessionInfo);

`embed.resetSessionInfo()`

Description: Resets the session information, clearing any user-specific data.
Usage:
```
embed.resetSessionInfo();
```

`embed.showBoloContainer()`

Description: Shows the embed container if it’s currently hidden.
Usage:
```
embed.showBoloContainer();
```

`embed.hideBoloContainer()`

Description: Hides the embed container.
Usage:
```
embed.hideBoloContainer();
```

Understanding `setSessionInfo` and Contact Configuration

The setSessionInfo function is essential for managing contact details relative to a session. It allows the system to associate specific contacts with a given session, which can be defined or updated dynamically.

function setSessionInfo() {
  const sessionInfo = document.getElementById("sessionInfo").value;
  let sessionInfoJSON = JSON.parse(sessionInfo);
  embed.setSessionInfo(sessionInfoJSON);
}

Contact Data Structure

Below is a table explaining each field in the contact object, along with whether the field is required or optional.

Key Name	Description	Required/Optional
`firstName`	The first name of the contact.	Required
`lastName`	The last name of the contact.	Required
`email`	The email address of the contact, used to send the document for signing.	Required
`phone`	The contact’s phone number.	Optional
`company`	The company or organization associated with the contact.	Optional
`jobTitle`	The job title of the contact within their company.	Optional
`streetAddress`	The contact's street address.	Optional
`city`	The city where the contact is located.	Optional
`postalCode`	The postal code of the contact's address.	Optional
`country`	The country of the contact’s address.	Optional
`state`	The state or region of the contact’s address.	Optional
`customFields`	An object containing additional fields for custom information, e.g.,	Optional
	`preferredContactMethod` (preferred contact method like email/phone) or
	`customerId` (unique identifier for the customer).

Code Example

In the contacts object, data is an array of objects that defines each contact's details. Each contact object can include the following fields, example of a complete contact object:

let config = {
  contacts: {
    data: [
      {
        firstName: "John", // Required
        lastName: "Doe",   // Required
        email: "[email protected]", // Required
        phone: "+1234567890", // Optional
        company: "Acme Corp", // Optional
        jobTitle: "Software Engineer", // Optional
        streetAddress: "123 Main St", // Optional
        city: "Metropolis", // Optional
        postalCode: "12345", // Optional
        country: "USA", // Optional
        state: "NY", // Optional
        customFields: { 
          preferredContactMethod: "email", // Optional
          customerId: 12345 // Optional
        }
      },
    ],
  },
};

This contact configuration helps to set or update session-based contacts that BoloSign will manage.

Contact Caching Based on Session Info

Contacts within the BoloSign embed system are cached uniquely for each session based on session info. Here’s how this caching works:

Initialization: When a session starts (either through initial configuration or by calling setSessionInfo), any contacts defined in contacts.data are cached for that session.
Session-Specific Caching: Each session has its own unique set of cached contacts. As long as the session continues, BoloSign will retain the initial contacts and cache any new contacts added by sending documents.
Session End: When a session is destroyed (via embed.destroy()), the cached contacts for that session are also cleared. This prevents contact data from persisting across sessions, ensuring data privacy and relevance.

This approach allows for contact management on a per-session basis, where each user or session operates with a unique contact set.

Basic HTML Structure and Code Sample

Below is a sample HTML structure and JavaScript code that demonstrates how to initialize and interact with the BoloSign embed instance in a web application.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>BoloForms Embed Example</title>
    <style>
      #embed-container {
        position: relative;
        height: 600px;
        border: 1px solid #ccc;
        margin-bottom: 20px;
      }
    </style>
  </head>
  <body style="padding: 10px">
    <h1>BoloForms Embed Example</h1>
    <div id="embed-container"></div>

    <button onclick="reInit()">Initialize / Re-initialize</button>
    <button onclick="destroyInstance()">Destroy Instance</button>
    <button onclick="showBoloContainer()">Show Container</button>
    <button onclick="hideBoloContainer()">Hide Container</button>
    <button onclick="reloadIframe()">Reload Iframe</button>
    <button onclick="createPDF()">Create PDF</button>
    <button onclick="resetSessionInfo()">Reset Session Info</button>
    <input type="text" id="sessionInfo" placeholder="Session Info JSON object" />
    <button onclick="setSessionInfo()">Set Session Info</button>
    <input type="text" id="documentIdInput" placeholder="Enter Document ID" />
    <button onclick="openDocument()">Open Document</button>

    <script src="https://appscript-scripts.s3.ap-south-1.amazonaws.com/boloforms-embed-index.min.js"></script>
    <script>
      // Create an instance of BoloFormsEmbed
      let config = {
        containerId: "embed-container",
        token: "your-embed-key",
        iframeOpts: { width: "100%", height: "600px" },
        sessionInfo: "john-doe-123",
        contacts: {
          data: [
            {
              firstName: "John",
              lastName: "Doe",
              email: "[email protected]",
              phone: "+1234567890",
              company: "Acme Corp",
              jobTitle: "Software Engineer",
              streetAddress: "123 Main St",
              city: "Metropolis",
              postalCode: "12345",
              country: "USA",
              state: "NY",
              customFields: { preferredContactMethod: "email", customerId: 12345 },
            },
          ],
        },
      };
      let

 embed = new BoloFormsEmbed(config);

      function reInit() { embed = new BoloFormsEmbed(config); }
      function destroyInstance() { embed.destroy(); }
      function showBoloContainer() { embed.showBoloContainer(); }
      function hideBoloContainer() { embed.hideBoloContainer(); }
      function reloadIframe() { embed.reloadIframe(); }
      function createPDF() { embed.createPDF(); }
      function resetSessionInfo() { embed.resetSessionInfo(); }
      function openDocument() {
        const documentId = document.getElementById("documentIdInput").value;
        embed.openDocument(documentId);
      }
      function setSessionInfo() {
        const sessionInfo = document.getElementById("sessionInfo").value;
        let sessionInfoJSON = JSON.parse(sessionInfo);
        embed.setSessionInfo(sessionInfoJSON);
      }
    </script>
  </body>
</html>

This sample demonstrates setting up, managing sessions, configuring contacts, and interacting with the BoloSign embed interface.

BoloSign Embedding System Documentation

Introduction

Overview

Basic Setup

Functions and Methods Explanations

embed.createPDF()

embed.destroy()

embed.reloadIframe()

embed.openDocument(documentId)

embed.setSessionInfo(sessionInfo)

embed.resetSessionInfo()

embed.showBoloContainer()

embed.hideBoloContainer()

Understanding setSessionInfo and Contact Configuration