Embedded Processes SDK

Article Overview

The following article describes how to embed EasySend processes with a Software Development Kit (SDK), to operate within your website or web-based applications.

Why use the SDK?

(See Figure 1 )

This SDK provides a toolset for application developers to seamlessly embed EasySend processes within your website or web-based applications to operate smoothly with a native look that matches your brand. Using the SDK can also improve the loading-time performance of the process.

The SDK can be included by embedding a <script> tag to be in the html of a web-based application. Once the SDK is imported to the webpage, the following is possible:

• Preload processes, to optimize their loading time
• Open Processes inside an <iframe>, while also synchronizing the user-scrolling between the host and the inner frame
• Register and act upon built-in process events (such as next page, previous page, completed, failed)

Figure 1: Example of embedded Process

Initial Setup

1. Install

To make the JavaScript SDK available to your application or site, install the package in your project using the npm installer

npm i easysend-sdk

2. Create a Player Handler

The Player handler is used for creating form handlers. It represents a single EasySend player instance, or a “run-time server”. To find the URL of the player server, open a process in the EasySend builder, and click on “preview” (see here for more information) or contact your EasySend admin.

const esPlayer = await EasySend.default.getPlayer("http://example.easysend.app")

3. Create a Form Handler

The form handler is used for working with a single form. It represents a single EasySend process and helps users to manage it. Form handler can be created by form ID or derived from a URL 

• From a constant Form ID:

const esForm = esPlayer.getForm("form_id", "customer_id")

• From a URL generated by the “generate_link” API call:

const esForm = esPlayer.useGeneratedLink("[url_from_generate_link_api]")

Working with EasySend forms

The SDK exposes the following capabilities:

The form events include: 

• prevPage: Called when user navigates to the previous form step
• nextPage: Called when user navigates to the next form step
• uploadSuccess: Called when form is submitted.
• uploadFailed: Called when form has failed to submit.

Note - Don't forget to release manager when you don't need it anymore:

JavaScriptJavaScript
eventListener.release()

Technical Requirements

• Update your environment servers to version 31.2.0 or above.
• The SDK can be used on your environment services only with verified URLs - to enable the SDK within your application, you need to provide EasySend with the URL/s in which the SDK will be implemented, to enable it on your environment servers

• Certain browsers may restrict the functionalities of iframes if the domain hosting the iframe differs from that of the iframe itself. To optimize the SDK capabilities, it's advisable to use a subdomain of the main (host) domain for the inner (iframe) component in which the process is embedded. For instance, if the host domain is "easysend.app", the iframe could effectively use "process.easysend.app" as a subdomain.

Design Guidelines and Implementation Limitations

• Process page headers and footer should be removed
• The Call To Action (CTA) should be placed in a visible area without requiring scrolling (above the fold)
• Forms should be relatively short and simple, for example, 101 form, get a quote request, FNOL
• Each page should contain a limited number of fields to fill out, typically between two to five
• Certain built-in functionalities, such as Co-Browsing or "Save and Continue," will open the process in a new tab rather than within its embedded context.
• Pop-up elements may appear unusual or out of place within the design
• Embedding processes into other pages is only feasible for processes with a single step or the initial step of a process
• It’s recommended to adjust the theme - buttons, page layout, a page with height, no header, to suit the specific requirements of each customer
• Welcome pages may not be necessary and can be replaced with informative titles for better user experience
• Data might be lost when navigating to a different location on the website (since a new RID might be generated every time).